Temporary storage control
The CICS temporary storage control program provides the application programmer with the ability to store data in temporary storage queues, either in main storage, or in auxiliary storage on a direct-access storage device. Data stored in a temporary storage queue is known as temporary data. Temporary storage control commands are provided to:
* Write data to a temporary storage queue (WRITEQ TS).
* Update data in a temporary storage queue (WRITEQ TS REWRITE).
* Read data from a temporary storage queue (READQ TS).
* Delete a temporary storage queue (DELETEQ TS).
If TS is omitted, the command is assumed to be for temporary storage, not for transient data which has similar commands.
Temporary storage queues
Temporary storage queues are identified by symbolic names which must be eight characters assigned by the originating task. Temporary data can be retrieved by the originating task or by any other task using the symbolic name assigned to it. Specific items (logical records) within a queue are referred to by relative position numbers. To avoid conflicts caused by duplicate names, a naming convention should be established, for example, the operator identifier, terminal identifier, or transaction identifier could be used as a prefix or suffix to each programmer-supplied symbolic name.
Temporary storage queues remain intact until they are deleted by the originating task or by any other task; prior to deletion, they can be accessed any number of times. Even after the originating task is terminated, temporary data can be accessed by other tasks through references to the symbolic name under which it is stored.
Temporary data can be stored either in main storage or in auxiliary storage. Generally, main storage should be used if the data is needed for short periods of time; auxiliary storage should be used if the data is to be kept for long periods of time. Data stored in auxiliary storage is retained after CICS termination and can be recovered in a subsequent restart, but data in main storage cannot be recovered. Main storage might be used to pass data from task to task, or for unique storage that allows programs to meet the requirement of CICS that they be quasi-reentrant (that is, serially reusable between entry and exit points of the program).
Typical uses of temporary storage control
A temporary storage queue having only one record can be treated as a single unit of data that can be accessed using its symbolic name. Using temporary storage control in this way provides a typical "scratch pad" capability. This type of storage should be accessed using the READQ TS command with the ITEM(1) option; failure to do so may cause the ITEMERR condition to be raised.
In general, temporary storage queues of more than one record should be used only when direct access or repeated access to records is necessary; transient data control provides facilities for efficient handling of sequential data sets.
Some uses of temporary storage queues follow:
Terminal paging. A task could retrieve a large master record from a direct-access data set, format it into several screen images (using basic mapping support), store the screen images temporarily in auxiliary storage, and then ask the terminal operator which "page" (screen image) is desired. The application programmer can provide a program (as a generalized routine or unique to a single application) to advance page by page, advance or back up a relative number of pages, and so on.
A suspend data set. Assume a data collection task is in progress at a terminal. The task reads one or more units of input and then allows the terminal operator to interrupt the process by some kind of coded input. If not interrupted, the task repeats the data collection process. If interrupted, the task writes its "incomplete" data to temporary storage and terminates. The terminal is now free to process a different transaction (perhaps a high-priority inquiry). When the terminal is available to continue data collection, the operator initiates the task in a "resume" mode, causing the task to recall its suspended data from temporary storage and continue as though it had not been interrupted.
Preprinted forms. An application program can accept data to be written as output on a preprinted form. This data can be stored in temporary storage as it arrives. When all the data has been stored, it can first be validated and then transmitted in the order required by the format of the preprinted form.
Write data to a temporary storage queue (WRITEQ TS)
WRITEQ TS
QUEUE(name)
FROM(data-area)
[LENGTH(data-value)]
[ITEM(data-area)[REWRITE]]
[SYSID(name)]
[MAIN|AUXILIARY]
[NOSUSPEND]
Conditions: INVREQ, IOERR,
ISCINVREQ, ITEMERR, LENGERR,
NOSPACE, NOTAUTH, QIDERR, SYSIDERR
This command is used to store temporary data (records) in a temporary storage queue in main or auxiliary storage.
If you use the MAIN option on this command to write data to a temporary storage queue on a remote system, the data is stored in main storage provided that the remote system is accessed by the CICS multi region operation (MRO) facility and that the remote system is at the same release level as the requesting system. If these conditions are not met, the data is stored in auxiliary storage.
The queue is identified in the QUEUE option. The FROM and LENGTH options are used to specify the record that is to be written to the queue, and its length.
If the ITEM option is specified, CICS assigns an item number to the record in the queue, and sets the data area supplied in that option to the item number. If the record starts a new queue, the item number assigned is 1; subsequent item numbers follow on sequentially.
The REWRITE option specifies that records are to be updated, in which case the ITEM option must also be specified to identify the item (record) that is to be replaced by the data identified in the FROM option. If the specified queue exists, but the specified item cannot be found, the ITEMERR condition occurs. If the
specified queue does not exist, the QIDERR condition occurs.
The following example shows how to write a record to a temporary storage queue in auxiliary storage:
EXEC CICS WRITEQ TS
QUEUE(UNIQNAME)
FROM(MESSAGE)
LENGTH(LENGTH)
ITEM(DREF)
The following example shows how to update a record in a temporary storage queue in main storage:
EXEC CICS WRITEQ TS
QUEUE('TEMPQ1')
FROM(DATAFLD)
LENGTH(40)
ITEM(ITEMFLD)
REWRITE
MAIN
Read data from temporary storage queue (READQ TS)
READQ TS
QUEUE(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]
[NUMITEMS(data-area)]
[ITEM(data-area)|NEXT]
[SYSID(name)]
Conditions: INVREQ, IOERR,
ISCINVREQ, ITEMERR, LENGERR,
NOTAUTH, QIDERR, SYSIDERR
This command is used to retrieve data from a temporary storage queue in main or auxiliary storage. The queue is identified in the QUEUE option.
The INTO option specifies the area into which the data is to be placed. The LENGTH option must specify a data area that contains the maximum length of record that the program will accept. If the record length exceeds the specified maximum length, it is truncated and the LENGERR condition occurs. After the retrieval operation, the data area specified in the LENGTH option is set to the record length (before any truncation occurred).
Alternatively, a pointer reference can be specified in the SET option. CICS then acquires an area large enough to hold the record and sets the pointer reference to the address of the record. The area is retained until another READQ TS command is executed. After the retrieval operation, the data area specified in the LENGTH option is set to the record length.
The ITEM and NEXT options are used to specify which record (item) within a queue is to be read. If the ITEM option is specified, the record with the specified item number is retrieved. If the NEXT option is in effect (either explicitly or by default), the next record after the last record to be retrieved (by any task) is retrieved. Therefore, if different tasks are to access the same queue and each task is to start at the beginning of the queue, the ITEM option must be used.
The following example shows how to read the first (or only) record from a temporary storage queue into a data area specified in the request:
EXEC CICS READQ TS
QUEUE(UNIQNAME)
INTO(DATA)
LENGTH(LDATA)
ITEM(1)
The following example shows how to read the next record from a temporary storage queue into a data area provided by CICS; the pointer reference specified by the SET option is set to the address of the storage area reserved for the data record.
EXEC CICS READQ TS
QUEUE(DESCRQ)
SET(PREF)
LENGTH(LENG)
NEXT
Delete temporary storage queue (DELETEQ TS)
DELETEQ TS
QUEUE(name)
[SYSID(name)]
Conditions: ISCINVREQ, NOTAUTH,
QIDERR, SYSIDERR
This command is used to delete all the temporary data associated with a temporary storage queue. All storage associated with the queue is freed.
Temporary data should be deleted at the earliest possible time to avoid using excessive amounts of storage.
Temporary storage control options
AUXILIARY
Specifies that the temporary storage queue is on a direct-access storage device in auxiliary storage.
FROM (data-area)
Specifies the data that is to be written to temporary storage.
INTO (data-area)
Specifies the data area into which the data is to be written. The data area may be any variable, array, or structure. If this option is specified, move-mode access is implied.
ITEM (parameter)
Specifies a half word binary value to be used with WRITEQ TS and READQ TS commands.
When used with a WRITEQ TS command in which the REWRITE option is not specified, 'parameter' must be a data area that is to be set to the item (record) number assigned to this record in the queue. If the REWRITE option is specified, the data area specifies the item in the queue that is to be replaced.
When used with a READQ TS command, 'parameter' specifies the item number of the logical record to be retrieved from the queue. The parameter must be a data value that is to be taken as the relative number of the logical record to be retrieved. This number may be the number of any item that has been written to the Temporary storage queue.
LENGTH (parameter)
Specifies the length (as a half word binary value) of the data to be used with WRITEQ TS and READQ TS commands.
For a WRITEQ TS command, the parameter must be a data value that is the length of the data that is to be written.
For a READQ TS command with the INTO option, the parameter must be a data area that specifies the maximum length of data that the program is prepared to handle. If the value specified is less than zero, zero is assumed. If the length of the data exceeds the value specified, the data is truncated to that value and the LENGERR condition occurs. On completion of the retrieval operation, the data area is set to the original length of the data.
For a READQ TS command with the SET option, the parameter must be a data area. On completion of the retrieval operation, the data area is set to the length of the data.
MAIN
Specifies that the temporary storage queue is in main storage.
NEXT
Specifies that the next sequential logical record following the last record to be retrieved (by any task) is to be retrieved.
NOSUSPEND
Specifies that application program suspension for the NOSPACE condition is to be inhibited.
NUMITEMS
Specifies a half word binary field into which CICS stores a number indicating how many items there are in the queue.
QUEUE (name)
Specifies the symbolic name of the queue to be written to, read from, or deleted.
If the queue name appears in the TST, and the entry is marked as remote, the request is shipped to a remote system.
The name must be alphanumeric, must be eight characters in length, must be unique within the CICS system, and must not be solely binary zeros.
Do not use the characters X'DF' as a queue name prefix; these characters are reserved for CICS use. Also, using any of the following in queue name prefixes can have unpredictable consequences:
1. Embedded blanks
2. Hexadecimal X'AA' through X'AF'
3. Hexadecimal X'BA' through X'BF'
4. Hexadecimal X'CA' through X'CF'
5. Hexadecimal X'DA' through X'DF'
6. Hexadecimal X'EA' through X'EF'
7. Hexadecimal X'FA' through X'FF'
REWRITE
Specifies that the existing record in the queue is to be overwritten with the data provided. If the REWRITE option is specified, the ITEM option must also be specified. If the specified queue does not exist, the QIDERR condition occurs. If the correct item within an existing queue cannot be found, the ITEMERR condition occurs but the data is not stored.
SET (ptr-ref)
Specifies the pointer reference that is to be set to the address of the retrieved data. If this option is specified, locate-mode access is implied.
SYSID (name) (remote systems only)
Specifies the name of the system whose resources are to be used for intercommunication facilities. The name can be up to four characters in length.
Temporary storage control exceptional conditions
INVREQ
Occurs when a WRITEQ TS command specifies a queue:
That is locked and awaiting ISC session recovery (see the CICS/MVS Installation Guide for details.), or
With a symbolic name that is all binary zeros.
This condition also occurs for a READQ TS or DELETEQ TS command when the record to be retrieved has been created by a DFHTS TYPE=PUT macro.
Default action: terminate the task abnormally.
IOERR
Occurs when there is an unrecoverable input/output error.
Default action: terminate the task abnormally.
ISCINVREQ
Occurs when the remote system indicates a failure which does not correspond to a known condition.
Default action: terminate the task abnormally.
ITEMERR
Occurs when:
The item number specified or implied by a READQ TS command,
Or a WRITEQ TS command with the REWRITE option, is invalid (that is, outside the range of entry numbers assigned for the queue).
The maximum number of items (32767) is exceeded.
Default action: terminate the task abnormally.
LENGERR
Occurs if:
The length of the stored data is greater than the value specified by
the LENGTH option for move-mode input operations, or
The length of the stored data specified by the WRITEQ TS command is zero or negative.
Default action: terminate the task abnormally.
NOSPACE
Occurs when insufficient space is available in the temporary storage data set to contain the data.
Default action: suspend the task until space becomes available as it is released by other tasks; then return normally.
NOTAUTH
Occurs when a resource security check has failed. Use of SYSID will always raise the NOTAUTH condition when resource security level checking is in effect (RSLC=YES in the PCT). The reasons for the failure are the same as for abend code AEY7, as described in the CICS/MVS Messages and Codes manual.
Default action: terminate the task abnormally.
QIDERR
Occurs when the queue specified by a READQ TS command, or by a WRITEQ TS command with the REWRITE option cannot be found, either in main storage or in auxiliary storage.
Default action: terminate the task abnormally.
SYSIDERR
Occurs when the SYSID option specifies either a name which is not defined in the intersystem table, or a system to which the link is closed.
Default action: terminate the task abnormally.
Wednesday, December 24, 2008
Tuesday, December 23, 2008
Transient data control
Transient data control
The CICS transient data control program provides a generalized queuing facility. Data can be queued (stored) for subsequent internal or external processing. Selected data, specified in the application program, can be routed to or from predefined symbolic destinations, either intra partition or extra partition.
Destinations are intra partition if associated with a facility allocated to the CICS region, and extra partition if the data is directed to a destination that is external to the CICS region. The destinations must be defined in the destination control table (the DCT) by the system programmer when the CICS system is generated.
Transient data control commands are provided to:
* Write data to a transient data queue (WRITEQ TD).
* Read data from a transient data queue (READQ TD).
* Delete an intra partition transient data queue (DELETEQ TD).
* Write data to transient data queue (WRITEQ TD)
WRITEQ TD
QUEUE(name)
FROM(data-area)
[LENGTH(data-value)]
[SYSID(name)]
Conditions: DISABLED, IOERR,
ISCINVREQ, LENGERR, NOSPACE,
NOTAUTH, NOTOPEN, QIDERR, SYSIDERR
This command is used to write transient data to a predefined symbolic destination. The destination (queue) is identified in the QUEUE option.
The FROM option specifies the data to be written to the queue, and the LENGTH option specifies the record length. The LENGTH option need not be specified for extra partition queues of fixed-length records if the length is known and a data area of the correct size is available. If SYSID is specified, LENGTH must be specified as well.
The following example shows how to write data to a predefined symbolic destination; in this case, the control system messages log (CSML):
EXEC CICS WRITEQ TD
QUEUE('CSML')
FROM(MESSAGE)
LENGTH(LENG)
Read data from transient data queue (READQ TD)
READQ TD
QUEUE(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]
[SYSID(name)]
[NOSUSPEND]
Conditions: DISABLED, IOERR,
ISCINVREQ, LENGERR, NOTAUTH,
NOTOPEN, QBUSY, QIDERR, QZERO,
SYSIDERR
This command is used to read transient data from a predefined symbolic source. The source (queue) is identified in the QUEUE option.
Reading a record from an intra partition transient data queue defined as reusable is destructive; it can only be read once.
The INTO option specifies the area into which the data is to be placed. The LENGTH option must specify a data area that contains the maximum length of record that the program will accept. If the record exceeds this value, it is truncated and the LENGERR condition occurs. After the retrieval operation, the data area
specified in the LENGTH option is set to the record length (before any truncation occurred). The LENGTH option need not be specified for extra partition queues of fixed-length records if the length is known and a data area of the correct size is available. If SYSID is specified, LENGTH must be specified as well.
Alternatively, a pointer reference can be specified in the SET option. CICS then acquires an area large enough to hold the record and sets the pointer reference to the address of that area. The area is retained until another transient data command is executed. After the retrieval operation, the data area specified in the LENGTH option is set to the record length.
If automatic task initiation is being used(the HANDLE CONDITION QZERO command should be included to ensure that termination of an automatically initiated task only occurs when the queue is empty.
The following example shows how to read a record from an intra partition data set (queue), which in this case is the control system message log (CSML), into a data area specified in the request:
EXEC CICS READQ TD
QUEUE('CSML')
INTO(DATA)
LENGTH(LENG)
The following example shows how to read a record from an extra partition data set (queue) having fixed-length records into a data area provided by CICS; the pointer reference specified by the SET option is set to the address of the storage area reserved for the data record. It is assumed that the record length is known.
EXEC CICS READQ TD
QUEUE(EX1)
SET(PREF)
Delete an intra partition transient data queue (DELETEQ TD)
DELETEQ TD
QUEUE(name)
[SYSID(name)]
Conditions: DISABLED, ISCINVREQ,
NOTAUTH, QIDERR, SYSIDERR
This command is used to delete all of the transient data associated with a particular intra partition destination (queue). All storage associated with the destination is released (reallocated).
This command must be used to release the storage associated with a destination specified as no reusable in the DCT. Otherwise, the storage remains allocated to the destination; the data and the amount of storage associated with the destination continue to grow whenever a WRITEQ TD command refers to the destination.
The CICS transient data control program provides a generalized queuing facility. Data can be queued (stored) for subsequent internal or external processing. Selected data, specified in the application program, can be routed to or from predefined symbolic destinations, either intra partition or extra partition.
Destinations are intra partition if associated with a facility allocated to the CICS region, and extra partition if the data is directed to a destination that is external to the CICS region. The destinations must be defined in the destination control table (the DCT) by the system programmer when the CICS system is generated.
Transient data control commands are provided to:
* Write data to a transient data queue (WRITEQ TD).
* Read data from a transient data queue (READQ TD).
* Delete an intra partition transient data queue (DELETEQ TD).
* Write data to transient data queue (WRITEQ TD)
WRITEQ TD
QUEUE(name)
FROM(data-area)
[LENGTH(data-value)]
[SYSID(name)]
Conditions: DISABLED, IOERR,
ISCINVREQ, LENGERR, NOSPACE,
NOTAUTH, NOTOPEN, QIDERR, SYSIDERR
This command is used to write transient data to a predefined symbolic destination. The destination (queue) is identified in the QUEUE option.
The FROM option specifies the data to be written to the queue, and the LENGTH option specifies the record length. The LENGTH option need not be specified for extra partition queues of fixed-length records if the length is known and a data area of the correct size is available. If SYSID is specified, LENGTH must be specified as well.
The following example shows how to write data to a predefined symbolic destination; in this case, the control system messages log (CSML):
EXEC CICS WRITEQ TD
QUEUE('CSML')
FROM(MESSAGE)
LENGTH(LENG)
Read data from transient data queue (READQ TD)
READQ TD
QUEUE(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]
[SYSID(name)]
[NOSUSPEND]
Conditions: DISABLED, IOERR,
ISCINVREQ, LENGERR, NOTAUTH,
NOTOPEN, QBUSY, QIDERR, QZERO,
SYSIDERR
This command is used to read transient data from a predefined symbolic source. The source (queue) is identified in the QUEUE option.
Reading a record from an intra partition transient data queue defined as reusable is destructive; it can only be read once.
The INTO option specifies the area into which the data is to be placed. The LENGTH option must specify a data area that contains the maximum length of record that the program will accept. If the record exceeds this value, it is truncated and the LENGERR condition occurs. After the retrieval operation, the data area
specified in the LENGTH option is set to the record length (before any truncation occurred). The LENGTH option need not be specified for extra partition queues of fixed-length records if the length is known and a data area of the correct size is available. If SYSID is specified, LENGTH must be specified as well.
Alternatively, a pointer reference can be specified in the SET option. CICS then acquires an area large enough to hold the record and sets the pointer reference to the address of that area. The area is retained until another transient data command is executed. After the retrieval operation, the data area specified in the LENGTH option is set to the record length.
If automatic task initiation is being used(the HANDLE CONDITION QZERO command should be included to ensure that termination of an automatically initiated task only occurs when the queue is empty.
The following example shows how to read a record from an intra partition data set (queue), which in this case is the control system message log (CSML), into a data area specified in the request:
EXEC CICS READQ TD
QUEUE('CSML')
INTO(DATA)
LENGTH(LENG)
The following example shows how to read a record from an extra partition data set (queue) having fixed-length records into a data area provided by CICS; the pointer reference specified by the SET option is set to the address of the storage area reserved for the data record. It is assumed that the record length is known.
EXEC CICS READQ TD
QUEUE(EX1)
SET(PREF)
Delete an intra partition transient data queue (DELETEQ TD)
DELETEQ TD
QUEUE(name)
[SYSID(name)]
Conditions: DISABLED, ISCINVREQ,
NOTAUTH, QIDERR, SYSIDERR
This command is used to delete all of the transient data associated with a particular intra partition destination (queue). All storage associated with the destination is released (reallocated).
This command must be used to release the storage associated with a destination specified as no reusable in the DCT. Otherwise, the storage remains allocated to the destination; the data and the amount of storage associated with the destination continue to grow whenever a WRITEQ TD command refers to the destination.
Monday, December 22, 2008
Passing data to other programs
You can pass data to another program when control is passed to that other program by means of a program control command.
The COMMAREA option of the LINK and XCTL commands specifies the name of a data area (known as a communication area) in which data is passed to the program being invoked. In the receiving program you must give this data area the name DFHCOMMAREA.
In a similar manner, the COMMAREA option of the RETURN command specifies the name of a communication area in which data is passed to the transaction identified in the TRANSID option.(The TRANSID option specifies a transaction that will be initiated when input is received from the terminal associated with the task.) The length of the communication area is specified in the LENGTH option; PL/I programs need not specify the length.
The invoked program receives the data as a parameter. The program must contain a definition of a data area to allow access to the passed data.
In an assembler language program, the data area should be a DSECT. The register used to address this DSECT must be loaded from DFHEICAP, which is in the DFHEISTG DSECT.
In a COBOL program, if a program passes a COMMAREA as part of a LINK, XCTL, or RETURN command, the data area can be in either working storage or the linkage section. A program receiving a COMMAREA should have the data specified in the linkage section. This applies whether the program is the receiving program during a LINK or XCTL command where a COMMAREA is passed or the initial program where a COMMAREA and TRANSID have been specified on the RETURN command of a previously called task.
In a PL/I program, the data area can have any name, but it must be declared as a based variable, based on the parameter passed to the program. The pointer to this based variable should be declared explicitly as a pointer rather than contextually by its appearance in the declaration for the area. This will prevent the generation of a PL/I error message. No ALLOCATE statement can be executed within the receiving program for any variable based on this pointer. This pointer must not be updated by the application program.
The receiving data area need not be of the same length as the original communication area; if access is required only to the first part of the data, the new data area can be shorter. It must not be longer than the length of the communication area being passed, because the results in this situation are unpredictable.
The invoked program can determine the length of any communication area that has been passed to it by accessing the EIBCALEN field in the EIB of the task. If no communication area has been passed, the value of EIBCALEN will be zero; otherwise, EIBCALEN will always contain the value specified in the LENGTH option of the LINK, XCTL, or RETURN command, regardless of the size of the data area in the invoked program.
When a communication area is passed by means of a LINK command, the invoked program is passed a pointer to the communication area itself. Any changes made to the contents of the data area in the invoked program are available to the invoking program, when control returns to it; to access any such changes, the program names the data area specified in the original COMMAREA option.
When a communication area is passed by means of an XCTL command, a copy of that area is made unless the area to be passed has the same address and length as the area that was passed to the program issuing the command. For example, if program A issues a LINK command to program B which, in turn, issues an
XCTL command to program C, and if B passes to C the same communication area that A passed to B, program C will be passed addressability to the communication area that belongs to A (not a copy of it) and any changes made by C will be available to A when control returns to it.
A communication area can be passed by means of a RETURN command issued at the highest logical level when control returns to CICS; in this case, a copy of the communication area is made, and addressability to the copy is passed to the first program of the next transaction.
The invoked program can access field EIBFN in the EIB to determine which type of command invoked the program. The field must be tested before CICS commands are issued. If a LINK or XCTL invoked the program, the appropriate code will be found in the field; if RETURN is used, no CICS commands will have been issued in the task, and the field will contain zeros.
The COMMAREA option of the LINK and XCTL commands specifies the name of a data area (known as a communication area) in which data is passed to the program being invoked. In the receiving program you must give this data area the name DFHCOMMAREA.
In a similar manner, the COMMAREA option of the RETURN command specifies the name of a communication area in which data is passed to the transaction identified in the TRANSID option.(The TRANSID option specifies a transaction that will be initiated when input is received from the terminal associated with the task.) The length of the communication area is specified in the LENGTH option; PL/I programs need not specify the length.
The invoked program receives the data as a parameter. The program must contain a definition of a data area to allow access to the passed data.
In an assembler language program, the data area should be a DSECT. The register used to address this DSECT must be loaded from DFHEICAP, which is in the DFHEISTG DSECT.
In a COBOL program, if a program passes a COMMAREA as part of a LINK, XCTL, or RETURN command, the data area can be in either working storage or the linkage section. A program receiving a COMMAREA should have the data specified in the linkage section. This applies whether the program is the receiving program during a LINK or XCTL command where a COMMAREA is passed or the initial program where a COMMAREA and TRANSID have been specified on the RETURN command of a previously called task.
In a PL/I program, the data area can have any name, but it must be declared as a based variable, based on the parameter passed to the program. The pointer to this based variable should be declared explicitly as a pointer rather than contextually by its appearance in the declaration for the area. This will prevent the generation of a PL/I error message. No ALLOCATE statement can be executed within the receiving program for any variable based on this pointer. This pointer must not be updated by the application program.
The receiving data area need not be of the same length as the original communication area; if access is required only to the first part of the data, the new data area can be shorter. It must not be longer than the length of the communication area being passed, because the results in this situation are unpredictable.
The invoked program can determine the length of any communication area that has been passed to it by accessing the EIBCALEN field in the EIB of the task. If no communication area has been passed, the value of EIBCALEN will be zero; otherwise, EIBCALEN will always contain the value specified in the LENGTH option of the LINK, XCTL, or RETURN command, regardless of the size of the data area in the invoked program.
When a communication area is passed by means of a LINK command, the invoked program is passed a pointer to the communication area itself. Any changes made to the contents of the data area in the invoked program are available to the invoking program, when control returns to it; to access any such changes, the program names the data area specified in the original COMMAREA option.
When a communication area is passed by means of an XCTL command, a copy of that area is made unless the area to be passed has the same address and length as the area that was passed to the program issuing the command. For example, if program A issues a LINK command to program B which, in turn, issues an
XCTL command to program C, and if B passes to C the same communication area that A passed to B, program C will be passed addressability to the communication area that belongs to A (not a copy of it) and any changes made by C will be available to A when control returns to it.
A communication area can be passed by means of a RETURN command issued at the highest logical level when control returns to CICS; in this case, a copy of the communication area is made, and addressability to the copy is passed to the first program of the next transaction.
The invoked program can access field EIBFN in the EIB to determine which type of command invoked the program. The field must be tested before CICS commands are issued. If a LINK or XCTL invoked the program, the appropriate code will be found in the field; if RETURN is used, no CICS commands will have been issued in the task, and the field will contain zeros.
Sunday, December 21, 2008
File control - commands, options, and conditions - II
Control operations
In this post I'll discuss the following group of functions in CICS.
* Interval control - comprising functions whose execution is dependent on time.
* Task control - comprising functions to temporarily relinquish control or to synchronize
resource usage.
* Program control - comprising functions affecting the flow of control between application
programs.
* Storage control - comprising functions to obtain and release areas of main storage.
* Transient data control - comprising functions for the transfer of data between CICS tasks and
between the CICS region and other regions.
* Temporary storage control - comprising functions for the temporary storage of data.
Interval control
The CICS interval control program, in conjunction with a time-of-day clock maintained by CICS, provides functions that can be performed at the correct time; such functions are called time-controlled functions. The time of day is obtained from the operating system at intervals whose frequency, and thus the accuracy of the time-of-day clock, depends on the task mix and the frequency of task switching operations. Using interval control commands you can:
* Request the current date and time of day (ASKTIME)
* Select the format of date and time (FORMATTIME)
* Delay the processing of a task (DELAY)
* Request notification when specified time has expired (POST)
* Wait for an event to occur (WAIT EVENT)
* Start a task and store data for the task (START)
* Retrieve data stored (by a START command) for a task (RETRIEVE)
* Cancel the effect of previous interval control commands (CANCEL).
Request current date and time of day (ASKTIME)
ASKTIME|
[ABSTIME(data-area)]|
You use this command to update the date and CICS time-of-day clock, and the fields EIBDATE and EIBTIME in the EIB. These two fields contain initially the date and time when the task started. The command returns the current time in the form of the number of milliseconds since 0000 hours on January 1, 1900.
The following example shows you how the ABSTIME option works:
EXEC CICS ASKTIME ABSTIME(utime)
After execution, 'utime' might contain the value 002694057952138 in milliseconds.
Select the format of date and time (FORMATTIME)
FORMATTIME
ABSTIME(data-value)
[YYDDD(data-area)]
[YYMMDD(data-area)]
[YYDDMM(data-area)]
[DDMMYY(data-area)]
[MMDDYY(data-area)]
[DATE(data-area)]
[DATEFORM(data-area)]
[DATESEP[(data-area)]]
[DAYCOUNT(data-area)]
[DAYOFWEEK(data-area)]
[DAYOFMONTH(data-area)]
[MONTHOFYEAR(data-area)]
[YEAR(data-area)]
[TIME(data-area)
[TIMESEP[(data-area)]]]
You use this command to transform the absolute date and/or time into any of a variety of formats.
The following example shows the effect of some of the options of the command:
EXEC CICS FORMATTIME ABSTIME(utime)
DATESEP('-') DDMMYY(date)
TIME(time) TIMESEP
Task control
The CICS task control program provides functions that synchronize task activity, or that control the use of resources.
CICS processes tasks according to priorities assigned by the system programmer. Control of the processor is given to the highest priority task that is ready to be processed and is returned to the operating system when no further work can be done by CICS or by user-written application programs.
Task control commands are provided to:
* Suspend a task (SUSPEND).
* Schedule the use of a resource by a task (ENQ and DEQ).
A task can issue the SUSPEND command to relinquish control and allow tasks higher on the active chain to proceed. This facility can be used to prevent processor-intensive tasks from monopolizing the processor. As soon as no other task higher on the active chain is waiting to be processed, control is returned to the issuing task; that is, the task remains dispatch able.
Scheduling the use of a resource by a task is sometimes useful in order to protect the resource from concurrent use by more than one task, that is, to make the resource serially reusable. Each task that is to use the resource issues an ENQ (enquire) commands. The first task to do so has the use of the resource immediately, but subsequent ENQ commands for the resource, issued by other tasks, result in those tasks being suspended until the resource is available. Each task using the resource should issue a DEQ (dequeue) command when it has finished with it. The resource then becomes available and the next task to have issued an ENQ command is resumed and given use of the resource. The other tasks obtain the resource in turn, in the order in which they enquired upon it.
Program control
The CICS program control program governs the flow of control between application programs in a CICS system. The name of an application program referred to in a program control command must have been defined as a program to CICS.
Program control commands are provided to:
* Link one user-written application program to another, anticipating subsequent return to the
requesting program (LINK). The COMMAREA option allows data to be passed to the
requested application program.
* Transfer control from one user-written application program to another, with no return to the
requesting program (XCTL). The COMMAREA option allows data to be passed to the
requested application program.
* Return control from one user-written application program to another or to CICS (RETURN).
The COMMAREA option allows data to be passed to a newly-initiated transaction.
* Load a designated application program, table, or map into main storage and return control to
the requesting program (LOAD).
* Delete a previously loaded application program, table, or map from main storage (RELEASE).
Application program logical levels
Application programs running under CICS are executed at various logical levels. The first program to receive control within a task is at the highest logical level. When an application program is linked to another, expecting an eventual return of control, the linked-to program is considered to reside at the next lower logical level. When control is simply transferred from one application program to another, without expecting return of control, the two programs are considered to reside at the same logical level.
Link to another program anticipating return (LINK)
LINK
PROGRAM(name)
[COMMAREA(data-area)
[LENGTH(data-value)]]
Conditions: NOTAUTH, PGMIDERR,
LENGERR
This command is used to pass control from an application program at one logical level to an application program at the next lower logical level. If the linked-to program is not already in main storage, it will be loaded. When the RETURN command is executed in the linked-to program, control is returned to the program initiating the linkage at the next sequential executable instruction.
The following example shows how to request a link to an application program called PROG1:
EXEC CICS LINK PROGRAM('PROG1')
The LENGTH option specifies the length of the data being passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are Unpredictable and may result in the LENGERR condition being set.
The linked-to program operates independently of the program that issues the LINK command with regard to handling exceptional conditions, attention identifiers, and abends. For example, the effects of HANDLE commands in the linking program are not inherited by the linked-to program, but the original HANDLE commands are restored on return to the linking program. Figure 40 illustrates the concept of logical levels.
Transfer program control (XCTL)
XCTL
PROGRAM(name)
[COMMAREA(data-area)
[LENGTH(data-value)]]
Condition: NOTAUTH, PGMIDERR, LENGERR
This command is used to transfer control from one application program to another at the same logical level. The program from which control is transferred is released. If the program to which control is transferred is not already in main storage, it will be loaded.
The following example shows how to request a transfer of control to an application program called PROG2:
EXEC CICS XCTL PROGRAM('PROG2')
The LENGTH option specifies the length of the data to be passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are unpredictable and may result in the LENGERR condition being set.
Return program control (RETURN)
RETURN
[TRANSID(name)
[COMMAREA(data-area)
[LENGTH(data-value)]]]
Condition: INVREQ, LENGERR
This command is used to return control from an application program either to an application program at the next higher logical level or to CICS.
When the RETURN command is issued in a lower-level program (that is, a linked-to program), control will be passed back to the level that is one logical level higher than the program returning control. If the task is associated with a terminal, the TRANSID option can be used at the lower level to specify the transaction identifier of the next transaction to be associated with that terminal. The transaction identifier will come into play only after the highest logical level has relinquished control to CICS using the RETURN command, and after input has been received from the terminal. Any input entered from the terminal, other than an attention key, will be interpreted wholly as data. In addition, the COMMAREA option can be used to pass data to the new task that will be started
No resource security checking occurs on the RETURN TRANSID command. However, transaction security checking is still available when CICS attaches the returned transaction.
The LENGTH option specifies the length of the data to be passed. The LENGTH value being passed must not be greater than the length of the data area specified in the COMMAREA option. If it is, the results are Unpredictable and may result in the LENGERR condition being set. The COMMAREA and LENGTH options can be used only when the RETURN command is returning control to CICS; the INVREQ condition will occur otherwise. If the COMMAREA option specifies a zero value as the address of the data area, INVREQ is returned.
File control - commands, options, and conditions - I
Read a record (READ)
READ
FILE¹(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]²
RIDFLD(data-area)
[KEYLENGTH(data-value)³[GENERIC]4]
[SYSID(name)]
[RBA4|RRN4|DEBKEY5|DEBREC5]
[GTEQ|EQUAL]4.
[UPDATE]
Conditions: DISABLED, FILENOTFOUND6,
DUPKEY4, ILLOGIC4, INVREQ, IOERR,
ISCINVREQ, LENGERR, NOTAUTH, NOTFND,
NOTOPEN, SYSIDERR
You use this command to read a record, via a file, from a direct access data set on a local or remote system.
If you include the UPDATE option, you must identify the record to be updated by the record identification field specified in the RIDFLD option. Immediately upon completion of a READ UPDATE command, the RIDFLD data area is available for reuse by the application program.
You can specify only one update operation per data set within a transaction at any given time. Further, to avoid deadlock when accessing a VSAM data set, your next command to the data set should be a REWRITE, DELETE without RIDFLD, or UNLOCK.
The following example shows you how to read a record from a data set, via a file named 'MASTER', into a specified data area:
EXEC CICS READ
INTO(RECORD)
FILE('MASTER')
RIDFLD(ACCTNO)
Write a record (WRITE)
You use this command to write a record to a direct access data set on a local or remote system. For example:
EXEC CICS WRITE
FROM(RECORD)
LENGTH(DATLEN)
FILE('MASTER')
RIDFLD(KEYFLD)
For a VSAM entry-sequenced data set (ESDS), the record is always added at the end of the data set. VSAM does not use the identification field specified in RIDFLD when calculating the RBA of the new record, but the new RBA is returned to the application in the record identification field specified in the RIDFLD option.
For a VSAM KSDS, the record is added in the location specified by the associated key; this location may be anywhere in the data set. For VSAM data sets, the key in the record and the key in the RIDFLD identification field must be the same.
Records for ESDS and KSDS data sets can be either fixed length or variable length. Those for a relative record data set must be fixed length. MASSINSERT operations must proceed with ascending keys, and must be terminated by an UNLOCK before any other request to the same data set.
Minimum function BMS
Minimum function BMS supports the IBM 3270 and IBM 3270-like range of displays and printers (but not SCS printers).
Screen layout design
The features of the 3270 system allow screen layouts to be designed for operator convenience and efficiency. The success of an online system depends on its ease-of-use, screen clarity, and terminal operator acceptance. The following features of some 3270 displays make it easier for the layout designer to fulfil the requirements:
* Color
* Field highlighting
* Programmed symbols
* Easy correction
* Numeric shift for numeric data
* Validation
* Field delimiters or stoppers (to control the length of data entered).
The first step in designing 3270 screen layouts is to divide the screen into functional areas such as a title area, an application data area, and a message area.
Defining a map set
You use the DFHMSD macro to define a set of maps, that is, a 'map set'. The macro consists of operands that define characteristics of the map, or maps,Comprising the map set. Some operands specified in DFHMSD can be overridden, for individual maps or fields that make up the map set, by operands in the map(DFHMDI) and field (DFHMDF) definition macros.
Defining maps within a map set
Each map in a map set is defined using the DFHMDI macro. This macro is similar in form to DFHMSD. It allows you to override some of the options inherited from DFHMSD, and to specify some new ones.
Defining fields within a BMS map
The DFHMDF macro is used to specify initial attributes to be given to fields within a map.
You use DFHMDF to specify the following:
* The one-to-seven character name of the field. You only have to name fields if your application
program refers to them. Only named fields appear in the Symbolic description map.
* The position of the start of the field relative to the map origin. This is the position of the
attribute byte for the field (POS operand).
* The length of the field excluding its attribute byte (LENGTH operand). Specifying the length of
a field does not cause BMS to delimit it with "stopper" fields; You must do that yourself either
by making successive fields contiguous, or by inserting fields with ATTRB=PROT.
* A field cannot extend beyond the right-hand edge of the map, that is, it cannot "wrap" around
the display.
* Whether data placed in the field is to be left-or right-justified. (JUSTIFY operand.)
* What character must be used to pad a justified field? (JUSTIFY=BLANK or JUSTIFY=ZERO.)
* The initial contents of the field. (INITIAL or XINIT operand.)
* Attributes of the field, for example, skip, protect, no display. (ATTRB operand.)
* Extended data stream attributes of the field. (COLOR, HILIGHT, OUTLINE, PS, SOSI,
TRANSP, and VALIDN operands.)
* A picture to be used to edit input. (PICIN and PICOUT operands.)
Terminating a map set definition
The macro DFHMSD TYPE=FINAL terminates a map set definition. It is coded as follows:
mapset DFHMSD TYPE=FINAL
Assembling and cataloging BMS maps
You assemble a BMS map definition to generate either a symbolic description map or a physical map. The CICS/MVS Operations Guide describes how to assemble and catalog the maps.
Symbolic description map
A symbolic description map set definition (DFHMSD TYPE=DSECT) is assembled, and cataloged in the source statement library. The member name is usually the same as the map set name, but it need not be. Alternatively, the symbolic description map can be copied or inserted directly into the application program.
Physical map
A physical map set definition (DFHMSD TYPE=MAP) is assembled, link edited, and cataloged in the CICS load library.
When you catalog the physical map, consider whether to add a suffix to its name (specified with the NAME statement). The reason for suffixing a map is that you might want to produce alternative versions of it for different terminal models.
Map set suffixing
If you want to execute the same transaction from more than one type of terminal, you might need to use BMS map set suffixing. If you are prepared to use the same map to format data for all your terminals, you need not read the rest of this section. If however, you wish to organize output data according to the terminal in use, making best use of its features, you ought to consider suffixing map sets.
For example, if you have displays with screens of different sizes, you might want to arrange display fields differently for each size of screen, ensuring that each display appears "balanced." You add a different suffix to each version of the same map. When a mapping operation is requested by a BMS command, CICS adds a suffix to the map set name specified in the command, and attempts to load a map set with that suffixed name.
READ
FILE¹(name)
{INTO(data-area)|SET(ptr-ref)}
[LENGTH(data-area)]²
RIDFLD(data-area)
[KEYLENGTH(data-value)³[GENERIC]4]
[SYSID(name)]
[RBA4|RRN4|DEBKEY5|DEBREC5]
[GTEQ|EQUAL]4.
[UPDATE]
Conditions: DISABLED, FILENOTFOUND6,
DUPKEY4, ILLOGIC4, INVREQ, IOERR,
ISCINVREQ, LENGERR, NOTAUTH, NOTFND,
NOTOPEN, SYSIDERR
You use this command to read a record, via a file, from a direct access data set on a local or remote system.
If you include the UPDATE option, you must identify the record to be updated by the record identification field specified in the RIDFLD option. Immediately upon completion of a READ UPDATE command, the RIDFLD data area is available for reuse by the application program.
You can specify only one update operation per data set within a transaction at any given time. Further, to avoid deadlock when accessing a VSAM data set, your next command to the data set should be a REWRITE, DELETE without RIDFLD, or UNLOCK.
The following example shows you how to read a record from a data set, via a file named 'MASTER', into a specified data area:
EXEC CICS READ
INTO(RECORD)
FILE('MASTER')
RIDFLD(ACCTNO)
Write a record (WRITE)
You use this command to write a record to a direct access data set on a local or remote system. For example:
EXEC CICS WRITE
FROM(RECORD)
LENGTH(DATLEN)
FILE('MASTER')
RIDFLD(KEYFLD)
For a VSAM entry-sequenced data set (ESDS), the record is always added at the end of the data set. VSAM does not use the identification field specified in RIDFLD when calculating the RBA of the new record, but the new RBA is returned to the application in the record identification field specified in the RIDFLD option.
For a VSAM KSDS, the record is added in the location specified by the associated key; this location may be anywhere in the data set. For VSAM data sets, the key in the record and the key in the RIDFLD identification field must be the same.
Records for ESDS and KSDS data sets can be either fixed length or variable length. Those for a relative record data set must be fixed length. MASSINSERT operations must proceed with ascending keys, and must be terminated by an UNLOCK before any other request to the same data set.
Minimum function BMS
Minimum function BMS supports the IBM 3270 and IBM 3270-like range of displays and printers (but not SCS printers).
Screen layout design
The features of the 3270 system allow screen layouts to be designed for operator convenience and efficiency. The success of an online system depends on its ease-of-use, screen clarity, and terminal operator acceptance. The following features of some 3270 displays make it easier for the layout designer to fulfil the requirements:
* Color
* Field highlighting
* Programmed symbols
* Easy correction
* Numeric shift for numeric data
* Validation
* Field delimiters or stoppers (to control the length of data entered).
The first step in designing 3270 screen layouts is to divide the screen into functional areas such as a title area, an application data area, and a message area.
Defining a map set
You use the DFHMSD macro to define a set of maps, that is, a 'map set'. The macro consists of operands that define characteristics of the map, or maps,Comprising the map set. Some operands specified in DFHMSD can be overridden, for individual maps or fields that make up the map set, by operands in the map(DFHMDI) and field (DFHMDF) definition macros.
Defining maps within a map set
Each map in a map set is defined using the DFHMDI macro. This macro is similar in form to DFHMSD. It allows you to override some of the options inherited from DFHMSD, and to specify some new ones.
Defining fields within a BMS map
The DFHMDF macro is used to specify initial attributes to be given to fields within a map.
You use DFHMDF to specify the following:
* The one-to-seven character name of the field. You only have to name fields if your application
program refers to them. Only named fields appear in the Symbolic description map.
* The position of the start of the field relative to the map origin. This is the position of the
attribute byte for the field (POS operand).
* The length of the field excluding its attribute byte (LENGTH operand). Specifying the length of
a field does not cause BMS to delimit it with "stopper" fields; You must do that yourself either
by making successive fields contiguous, or by inserting fields with ATTRB=PROT.
* A field cannot extend beyond the right-hand edge of the map, that is, it cannot "wrap" around
the display.
* Whether data placed in the field is to be left-or right-justified. (JUSTIFY operand.)
* What character must be used to pad a justified field? (JUSTIFY=BLANK or JUSTIFY=ZERO.)
* The initial contents of the field. (INITIAL or XINIT operand.)
* Attributes of the field, for example, skip, protect, no display. (ATTRB operand.)
* Extended data stream attributes of the field. (COLOR, HILIGHT, OUTLINE, PS, SOSI,
TRANSP, and VALIDN operands.)
* A picture to be used to edit input. (PICIN and PICOUT operands.)
Terminating a map set definition
The macro DFHMSD TYPE=FINAL terminates a map set definition. It is coded as follows:
mapset DFHMSD TYPE=FINAL
Assembling and cataloging BMS maps
You assemble a BMS map definition to generate either a symbolic description map or a physical map. The CICS/MVS Operations Guide describes how to assemble and catalog the maps.
Symbolic description map
A symbolic description map set definition (DFHMSD TYPE=DSECT) is assembled, and cataloged in the source statement library. The member name is usually the same as the map set name, but it need not be. Alternatively, the symbolic description map can be copied or inserted directly into the application program.
Physical map
A physical map set definition (DFHMSD TYPE=MAP) is assembled, link edited, and cataloged in the CICS load library.
When you catalog the physical map, consider whether to add a suffix to its name (specified with the NAME statement). The reason for suffixing a map is that you might want to produce alternative versions of it for different terminal models.
Map set suffixing
If you want to execute the same transaction from more than one type of terminal, you might need to use BMS map set suffixing. If you are prepared to use the same map to format data for all your terminals, you need not read the rest of this section. If however, you wish to organize output data according to the terminal in use, making best use of its features, you ought to consider suffixing map sets.
For example, if you have displays with screens of different sizes, you might want to arrange display fields differently for each size of screen, ensuring that each display appears "balanced." You add a different suffix to each version of the same map. When a mapping operation is requested by a BMS command, CICS adds a suffix to the map set name specified in the command, and attempts to load a map set with that suffixed name.
Files and databases
CICS transactions can access files and databases, which can be on either a local or remote system. Files are processed by the CICS file control program, which allows you to read, add, update, delete (VSAM only), and browse records in VSAM and BDAM data sets. When you access files through the file control program, you do not have such considerations as buffer management, blocking and De-blocking, and access method dependencies.
DL/I databases give you a greater degree of data independence than file control does. You are presented with a logical view of the database in terms of hierarchy of segments. DL/I offer you facilities for manipulating these segments and you do not need to know how they are organized.
CICS has two programming interfaces to DL/I: the EXEC DLI interface, and the DL/I CALL interface.
You identify records in VSAM data sets by key, by relative byte address (RBA), or by relative record number (RRN).
To distinguish which format of record identification is to be used, the RBA and RRN options can be used on most file commands that access VSAM data sets. The options effectively define the format of the record identification field (RIDFLD). If neither the RBA nor the RRN option is specified, the RIDFLD option should contain a key to be used for accessing a VSAM KSDS, or a VSAM KSDS or ESDS by way of a path.
The RBA option specifies that the RIDFLD contains the relative byte address of the record to be accessed. A relative byte address is used to access a VSAM ESDS, and it may also be used to access a VSAM KSDS. However, if a KSDS is accessed in this way, the RBA of the record may change during the transaction as a result of another transaction adding records to, or deleting records from, the same data set.
The RRN option specifies that the RIDFLD contains the relative record number (the first record in a data set being numbered 1) of the record to be retrieved.
Operations involving use of VSAM keys may specify either a complete key or a generic (partial) key. (The one exception to this rule is when a record is written to a SAM KSDS. In this instance, the complete key must be specified in the RIDFLD option of the command.) When a generic key is used, its length must be specified in the KEY LENGTH option, and the GENERIC option must also be specified on the command. A generic key cannot have a key length equal to the full key length. That is, a generic key is defined to be of a length that is strictly less than that of the complete key.
For both complete and generic keys, the GTEQ option may also be specified on certain commands. The command then positions at, or applies to, the record in the data set with the next higher key if a matching key cannot be found. When a data set is being accessed by way of an alternate index path, the record identified is the one with the next higher alternative when a matching record cannot be found.
The application programmer should always, even when using generic keys, use an area of storage for the RIDFLD whose length is equal to the length of the complete key. This is because during a browse operation, after retrieving a record, CICS copies into the RIDFLD area the actual identifier of the record retrieved. In some cases, CICS will return to the application program a complete key, even when a generic key was specified on the command. An example of this is a generic browse through a VSAM KSDS where the complete key is returned to the application program on each READNEXT and READPREV command.
DL/I databases give you a greater degree of data independence than file control does. You are presented with a logical view of the database in terms of hierarchy of segments. DL/I offer you facilities for manipulating these segments and you do not need to know how they are organized.
CICS has two programming interfaces to DL/I: the EXEC DLI interface, and the DL/I CALL interface.
You identify records in VSAM data sets by key, by relative byte address (RBA), or by relative record number (RRN).
To distinguish which format of record identification is to be used, the RBA and RRN options can be used on most file commands that access VSAM data sets. The options effectively define the format of the record identification field (RIDFLD). If neither the RBA nor the RRN option is specified, the RIDFLD option should contain a key to be used for accessing a VSAM KSDS, or a VSAM KSDS or ESDS by way of a path.
The RBA option specifies that the RIDFLD contains the relative byte address of the record to be accessed. A relative byte address is used to access a VSAM ESDS, and it may also be used to access a VSAM KSDS. However, if a KSDS is accessed in this way, the RBA of the record may change during the transaction as a result of another transaction adding records to, or deleting records from, the same data set.
The RRN option specifies that the RIDFLD contains the relative record number (the first record in a data set being numbered 1) of the record to be retrieved.
Operations involving use of VSAM keys may specify either a complete key or a generic (partial) key. (The one exception to this rule is when a record is written to a SAM KSDS. In this instance, the complete key must be specified in the RIDFLD option of the command.) When a generic key is used, its length must be specified in the KEY LENGTH option, and the GENERIC option must also be specified on the command. A generic key cannot have a key length equal to the full key length. That is, a generic key is defined to be of a length that is strictly less than that of the complete key.
For both complete and generic keys, the GTEQ option may also be specified on certain commands. The command then positions at, or applies to, the record in the data set with the next higher key if a matching key cannot be found. When a data set is being accessed by way of an alternate index path, the record identified is the one with the next higher alternative when a matching record cannot be found.
The application programmer should always, even when using generic keys, use an area of storage for the RIDFLD whose length is equal to the length of the complete key. This is because during a browse operation, after retrieving a record, CICS copies into the RIDFLD area the actual identifier of the record retrieved. In some cases, CICS will return to the application program a complete key, even when a generic key was specified on the command. An example of this is a generic browse through a VSAM KSDS where the complete key is returned to the application program on each READNEXT and READPREV command.
How does CICS help you set up an online system?
After your system has been designed, the programming effort to turn the specification into a working application is normally divided between two groups: the people who install and maintain the system and those who write the application programs it will use. (We don't want to rule out the possibility of all this work being done by one heroic person.) CICS offers a variety of helpful features for both groups. Concentrating on the application programming side, CICS aids include:
A choice of programming language. You can write your application programs in assembler, COBOL, PL/I, or C language.
A command-level programming interface with CICS. You need know little about how CICS works. You request data or communication with terminals by issuing CICS commands that resemble those of the programming language you are using. A command language translator preprocesses the application source code, translating CICS commands into CALL statements in the language of the application program. It also provides useful diagnostics.
An execution diagnostic facility (EDF), for testing command-level application programs interactively.
A choice of programming language. You can write your application programs in assembler, COBOL, PL/I, or C language.
A command-level programming interface with CICS. You need know little about how CICS works. You request data or communication with terminals by issuing CICS commands that resemble those of the programming language you are using. A command language translator preprocesses the application source code, translating CICS commands into CALL statements in the language of the application program. It also provides useful diagnostics.
An execution diagnostic facility (EDF), for testing command-level application programs interactively.
Subscribe to:
Posts (Atom)