OpenTP1 Version 7 Programming Guide
To access a DAM file from a UAP in online mode (e.g., file reference or update), processing must be done in the transaction. If the DAM file open function is called before the transaction is started, terminate all the transactions started after the DAM file was opened, then close the DAM file.
To open a DAM file, use the function dc_dam_open() [CBLDCDAM ('OPEN')] in which the logical file name is specified. When the DAM file is opened, the file descriptor is returned as the name for identifying the file. For processing after the file is opened, specify this file descriptor in the function to access the file (e.g., file input, update, or output). To close the DAM file, use the function dc_dam_close() [CBLDCDAM('CLOS')] in which the file descriptor is specified. Shut down the file descriptor in the UAP even for processing after the file is opened.
A file descriptor becomes valid in the following cases:
Use the logical file name to logically shut down the DAM file, release the DAM file from the shutdown state, or reference the status of the DAM file during processing.
Consecutive blocks can be input/output collectively. When inputting/outputting a DAM file, specify an access block range as a structure in the corresponding function. The block range must be specified with the relative block number. More than one structure can be specified.
To reference a DAM file block, enter the block by using the function dc_dam_read() [CBLDCDAM('READ')]. At this time, you can also specify whether to allow another transaction to reference/update the block.
To update a DAM file block, enter the block by using the function dc_dam_read(), then call the function dc_dam_rewrite() [CBLDCDAM ('REWT')] to update the block.
Call the function dc_dam_write() [CBLDCDAM('WRIT')] when you want to overwrite a block without entering a block from a DAM file.
If a logical conflict is found during processing for a DAM file block, the UAP can call the function dc_dam_hold() [CBLDCDAM('HOLD')] to shut down the DAM file so that another UAP cannot access the DAM file. The UAP can also call the function dc_dam_release() [CBLDCDAM ('RLES')] to release the DAM file from the shutdown state.
The figure below shows the procedure for accessing DAM files in online mode.
Figure 4-2 Access to DAM files in online mode
If an error occurs during access from a transaction process to a DAM file, call the function abort() from the UAP in order to terminate the transaction process abnormally.
Depending on the function that accessed the file previously, an access to a block may cause return with an error. The result of access (normal return or error return) varies depending on whether the function for the access is called within the same transaction or from a different transaction. Tables 4-1 and 4-2 list functions which can access DAM file blocks if particular functions were previously called.
Table 4-1 Functions able to access the same block in one transaction (recoverable DAM files)
Previously called function | Function to be called | Results or error return value |
---|---|---|
No function for accessing a DAM file has been called in the transaction | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) |
Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_read (input for reference) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_read (input for reference, lock specified) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_read (input for update) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | Y | |
dc_dam_rewrite (update cancellation) | Y | |
dc_dam_write (output) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_rewrite (update cancellation) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_write (output) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y |
Table 4-2 Functions able to access the same block in different transaction (recoverable DAM files)
Previously called function | Function to be called | Results or error return value |
---|---|---|
No function for accessing a DAM file has been called in the transaction | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) |
Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_read (input for reference) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_read (input for reference, lock specified) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | DCDAMER_EXCER (01602)# | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | DCDAMER_EXCER(01602)# | |
dc_dam_read (input for update) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | DCDAMER_EXCER (01602)# | |
dc_dam_read (input for update) | DCDAMER_EXCER (01602)# | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | DCDAMER_EXCER(01602)# | |
dc_dam_rewrite (update) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | DCDAMER_EXCER (01602)# | |
dc_dam_read (input for update) | DCDAMER_EXCER (01602)# | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | DCDAMER_EXCER (01602)# | |
dc_dam_rewrite (update cancellation) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference, lock specified) | Y | |
dc_dam_read (input for update) | Y | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | Y | |
dc_dam_write (output) | dc_dam_read (input for reference) | Y |
dc_dam_read (input for reference lock specified) | DCDAMER_EXCER (01602)# | |
dc_dam_read (input for update) | DCDAMER_EXCER (01602)# | |
dc_dam_rewrite (update) | DCDAMER_SEQER (01605) | |
dc_dam_rewrite (update cancellation) | DCDAMER_SEQER (01605) | |
dc_dam_write (output) | DCDAMER_EXCER (01602)# |
DAM service functions return with a DCDAMER_PROTO error ("01600" in the case of COBOL) for the following reasons. The reason varies with the function called:
The status of a DAM file in use can be referenced in online mode. Call the function dc_dam_status() [CBLDCDAM('STAT')] to reference the status of a DAM file. This function allows referencing of the following information:
When the function dc_dam_status() is called, the DAM service locks the file to acquire the information. Therefore, frequent use of this function may cause lock waits and reduced throughput. The status of a DAM file should be referenced in online mode as little as possible.
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.