OSC Management Features
This chapter describes OSC management features for controlling programs and intervals.
1. Overview
The EXEC CICS interface provides the following OSC management features to handle program execution, application flow control, temporary data storage, and data sharing between programs.
2. Program Control
Each OSC application is composed of one or more programs. Program control features are used to connect OSC programs to each other or to pass control from one program to another.
|
Program Control Commands
The following is a list of program control commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Retrieves information about a program, map set, or partition set in a region. |
|
Connects the active program to another program. |
|
Makes a copy of an application program, table, or map available for a task. |
|
Releases a loaded program, table or map. |
|
Ends the active program and returns control to the previously active program. |
|
Changes the definition of a program, map set, or partition set. |
|
Ends the active program and transfers control to another program. |
2.1. INQUIRE PROGRAM
Retrieves information about a program, map set, or partition set in a region.
-
Syntax
EXEC CICS INQUIRE PROGRAM [option …] END-EXEC.
-
Options
Option Description END
Ends browsing.
HOLDSTATUS
Returns an indicator that shows whether a copy of a module is loaded or not.
LANGUAGE
Returns a programming language.
NEXT
Repeats the INQUIRE command. Only one resource definition is returned.
PROGRAM
Specifies the name of a program, map set, or partition set up to eight characters.
REMOTENAME
Returns the eight-character name of the OSC region specified in the REMOTESYSTEM option.
REMOTESYSTEM
Returns the four-character name of the OSC region.
START
Starts browsing.
STATUS
Returns an indicator that shows whether a module is available or not.
TRANSID
Returns the four-character name of the transaction that is processed by a remote module.
The following options are not supported: APIST, CEDFSTATUS, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, COBOLTYPE, COPY, CONCURRENCY, DATALOCATION, DEFINESOURCE, DEFINETIME, DYNAMSTATUS, ENTRYPOINT, EXECKEY, EXECUTIONSET, INSTALLAGENT, INSTALLTIME, INSTALLUSRID, JVMCLASS, JVMPROFILE, JVMSERVER, LANGDEDUCED, LENGTH, LIBRARY, LIBRARYDSN, LOADPOINT, LPASTATUS, PROGTYPE, RESCOUNT, RUNTIME, SHARESTATUS and USECOUNT.
2.2. LINK
Connects the currently running program to another program.
This command connects the currently running program to another program. The target program is loaded into memory and executed automatically by the system. Program control will be given to the target program until it has finished execution; at this point, control will be returned to the program that invoked LINK. After control has been returned, program execution continues as usual. Data can be transferred to the target program by using some command options.
-
Syntax
EXEC CICS LINK [option …] END-EXEC.
-
Options
Option Description CHANNEL
Specifies the name of the channel to pass to the target program.
COMMAREA
Specifies the data storage to be sent to the target program.
DATALENGTH
Specifies the length of data from COMMAREA to be sent.
INPUTMSG
Specifies the data to be sent to the target program when it first executes the RECEIVE command.
INPUTMSGLEN
Specifies the length of the INPUTMSG.
LENGTH
Specifies the length of the COMMAREA.
PROGRAM
Specifies the name of the target program.
SYSID
Specifies the identifier of the system where the target program is located.
SYNCONRETURN
Specifies the processing of SYNPOINT after the successful completion of a server program in a mirror transaction.
TRANSID
Specifies the name of a mirror transaction. The program of a mirror transaction must be set to DFHMIRS.
|
The following BATCH MTPBATCH command can be used to run a program instead of LINK. LINK <program_name> |
2.3. LOAD
Makes a copy of an application program, table, or map available for a task.
-
Syntax
EXEC CICS LOAD [option …] END-EXEC.
-
Options
Option Description ENTRY
Specifies the pointer reference to be set to the address of the entry point of the program that has been loaded.
FLENGTH
Specifies a fullword binary area to be set to the length of the program, table, or map that has been loaded.
HOLD
Indicates that the loaded program, table, or map is not to be released when the task that issues the LOAD command is terminated.
LENGTH
Specifies a halfword binary area to be set to the length of the program, table, or map that has been loaded.
PROGRAM
Specifies the identifier of a program, table, or map to be loaded.
SET
Specifies the pointer reference to be set to the address of the program, table, or map to be loaded.
2.4. RELEASE
Releases a program, table, or map that has been loaded.
-
Syntax
EXEC CICS RELEASE [option …] END-EXEC.
-
Option
Option Description PROGRAM
Specifies the identifier of the program, table, or map to be released.
2.5. RETURN
Ends the currently running program and returns control to the previously running program. If no program exists for control to be returned to, control will be returned to the application server.
-
Syntax
EXEC CICS RETURN [option …] END-EXEC.
-
Options
Option Description CHANNEL
Specifies the name of a channel to be used by the next program.
COMMAREA
Specifies the data storage name to receive from the transaction program specified in the TRANSID.
IMMEDIATE
Indicates that the transaction specified in TRANSID will executed immediately, even if another transaction related to the current terminal is already waiting for execution.
INPUTMSG
Specifies the data passed to the next program through the first RECEIVE command.
INPUTMSGLEN
Specifies the length of the data to be received into INPUTMSG.
LENGTH
Specifies the COMMAREA length.
TRANSID
Indicates the transaction ID that will be executed when the corresponding terminal receives the next terminal input.
When the OSC system connects to a new program, OSC resources are immediately loaded into memory from disk. Therefore, the LOAD and the RELEASE commands used to load and release programs are not needed in OSC.
2.6. SET PROGRAM
Changes the definition of a program, map set, or partition set.
-
Syntax
EXEC CICS SET PROGRAM [option …] END-EXEC.
-
Options
Option Description PROGRAM
Specifies the identifier of a program, map set, or partition set to change.
STATUS
Specifies whether to enable a module (ENABLED) or not (DISABLED).
-
The following options are not supported: COPY, EXECUTIONSET, JVMCLASS, JVMPROFILE, RUNTIME and SHARESTATUS.
-
Only parsing is supported for END, NEXT, and START.
-
The following BATCH MTPBATCH command can be used to change STATUS instead of SET PROGRAM.
CEMT SET PROG<program_name> DIS | ENA
-
2.7. XCTL
Ends the currently running program and passes control to the target program. Unlike the LINK command, even if the target program invokes RETURN, control will not be returned to the program.
-
Syntax
EXEC CICS XCTL [option …] END-EXEC.
-
Options
Option Description CHANNEL
Specifies the channel name to be sent to the target program.
COMMAREA
Specifies the data storage to be sent to the target program.
LENGTH
Specifies the COMMAREA length.
INPUTMSG
Specifies the data passed to the next program through the first RECEIVE command.
INPUTMSGLEN
Specifies the length to send to INPUTMSG.
PROGRAM
Specifies the program name to which control will be returned.
3. Interval Control
OSC interval control features provide time-related program control commands. The interval control features are used to start new transactions after a specific period of time or suspend them for a specific time interval. They also can be used to cancel previous interval control commands.
The interval control commands consist of time-related commands and START commands.
-
Time-related commands
The following is a list of time-related commands. For more information about each command, refer to the respective section.
Command Description Retrieves the current date and time.
Cancels a DELAY or START command.
Accepts a date and time retrieved from the ASKTIME command or from EIBDATE and EIBTIME and converts it into a specified format.
Retrieves data stored for a task that was started by the START command.
-
START-related commands
The following is a list of START-related commands. For more information about each command, refer to the respective section.
Command Description Delays the processing of a task until a specified time or for a specified duration of time.
Starts processing a task at a specified time.
3.1. ASKTIME
Retrieves the current date and time. The date and time are stored in the EIBTIME and EIBDATE fields in the EIB. They are retrieved in absolute system date/time format, but can be converted to a desired format using the FORMATTIME command after the ASKTIME command.
-
Syntax
EXEC CICS ASKTIME [option …] END-EXEC.
-
Option
Option Description ABSTIME
Specifies a data area where the date and time will be stored in absolute date/time format.
3.2. CANCEL
Cancels a requested DELAY or START command. DELAY transactions that are past the delay time or START transactions that have reached the start time cannot be canceled.
-
Syntax
EXEC CICS CANCEL [option …] END-EXEC.
-
Options
Option Description REQID
Specifies the REQID to be canceled.
SYSID
Specifies the remote server that will execute the CANCEL command.
TRANSID
Specifies the transaction name.
3.3. DELAY
Delays the processing of a task until a specified time or for a specified time period.
-
Syntax
EXEC CICS DELAY [option …] END-EXEC.
-
Options
Option Description FOR
Specifies the duration of the delay. (Binary)
-
HOURS
-
MINUTES
-
SECONDS
-
MILLISECS
INTERVAL
Specifies the duration of the delay of a task. (Packed Decimal)
REQID
Specifies the identifier of a DELAY request. Using this option to specify the identifier of a DELAY request enables another program to cancel the DELAY request.
TIME
Specifies the time when the delay of a task will end. (Packed Decimal)
UNTIL
Specifies the time at the end of the delay. (Binary)
-
HOURS
-
MINUTES
-
SECONDS
-
3.4. FORMATTIME
This command accepts a date and time retrieved from the ASKTIME command or from EIBDATE and EIBTIME and converts it into a desired format.
-
Syntax
EXEC CICS FORMATTIME [option …] END-EXEC.
-
Options
Option Description ABSTIME
Specifies the data (absolute date and time) to convert.
DATE
Converts the data to the DATE type.
DATEFORM
Returns the date as MMDDYY.
DATESEP
Specifies the separator to separate the YEAR, MONTH, and DAY. If the DATESEP option is included with no separator specified, a slash (/) will be used by default.
DAYCOUNT
Returns the number of days since Jan. 1,1900.
DAYOFMONTH
Returns the number of days of the current month.
DAYOFWEEK
Returns the day number of the week (SUNDAY is 0, MONDAY is 1,… SATURDAY is 6).
DDMMYY
Returns the date as DAY/MONTH/YEAR, with YEAR containing the last two digits of the year. A separator separates the DAY, MONTH and YEAR.
DDMMYYYY
Returns the date as DAY/MONTH/YEAR, with YEAR containing four digits. A separator separates the DAY, MONTH, and YEAR.
FULLDATE
Returns the date as MMDDYYYY.
MILLISECONDS
Returns milliseconds specified by ABSTIME as a binary number, ranging from 0 to 999.
MMDDYY
Returns the date as MONTH/DAY/YEAR, with YEAR containing the last two digits of the year. A separator separates the DAY, MONTH, and YEAR.
MMDDYYYY
Returns the date as MONTH/DAY/YEAR, with YEAR containing four digits. A separator separates the MONTH, DAY, and YEAR.
MONTHOFYEAR
Returns the number of months that have passed since the beginning of the year.
TIME
Returns the time in the format HH:MM:SS. The default separator, which can be changed in the TIMESEP field, is a colon (:).
TIMESEP
Specifies the separator to be used in the TIME option.
YEAR
Returns the YEAR as four digits.
YYDDMM
Returns the date as YEAR/DAY/MONTH, with YEAR containing the last two digits of the year. A separator separates the YEAR, DAY, and MONTH.
YYMMDD
Returns the date as YEAR/MONTH/DAY, with YEAR containing the last two digits of the year. A separator separates the YEAR, MONTH, and DAY.
YYYYDDD
Returns the date as YEAR/DAY, with YEAR containing the last two digits of the year. Day indicates the number of days of a year.A separator separates the YEAR and DAY.
YYYYDDMM
Returns the date as YEAR/DAY/MONTH, with YEAR containing four digits. A separator separates the YEAR, DAY, and MONTH.
YYYYMMDD
Returns the date as YEAR/MONTH/DAY, with YEAR containing four digits. A separator separates the YEAR, MONTH, and DAY.
YYDDD
Returns the date as YEAR/DAY, with YEAR containing the last two digits of the year and day containing the number of days that have passed since the beginning of the year. A separator separates the YEAR and DAY.
3.5. RETRIEVE
Retrieves data stored for a task that was started by the START command.
-
Syntax
EXEC CICS RETRIEVE [option …] END-EXEC.
-
Options
Option Description INTO
Specifies the storage area for the retrieved data.
LENGTH
Specifies the length of the data storage area.
QUEUE
Specifies a data area that will be set to the QUEUE of the retrieved data.
RTERMID
Specifies a data area that will be set to the TERMID of the retrieved data.
RTRANSID
Specifies a data area that will be set to the TRANSID of the retrieved data.
SET
Specifies a pointer reference that will be set to the address of the retrieved data.
Only parsing is supported for WAIT.
3.6. START
Starts processing a task at a specified time.
-
Syntax
EXEC CICS START [option …] END-EXEC.
-
Options
Option Ddescription AFTER
Specifies the interval of time that must pass before the task is started.
-
HOURS
-
MINUTES
-
SECONDS
AT
Specifies when the new task must be started.
-
HOURS
-
MINUTES
-
SECONDS
CHANNEL
Specifies the name of a channel that is to be made available to the started task. This option cannot be used with the FROM option.
FROM
Specifies the data area that can be retrieved by using RETRIEVE in some future task.
INTERVAL
Specifies the interval of time that must pass before the task is started. (Packed Decimal)
LENGTH
Specifies the length of the data in the FROM option.
NOCHECK
Indicates that no response is to be received by the starting transaction. Error conditions are not returned for tasks that are started on a remote system.
QUEUE
Specifies the queue name to be used at the START request.
REQID
Specifies an identifier for the START request. This identifier can be used to cancel an unexpired START command. When the REQID option is not specified, the OSC application server creates a new request identifier. After the request is successfully performed, the OSC application server can retrieve the identifier using the EIBREQID option.
PROTECT
Indicates that the task will not be started until a syncpoint has been made. If the PROTECT option is used, an eight character REQID beginning with 'OxFC' is returned. If the PROTECT option is not used, an eight character REQID beginning with 'DF' is returned.
RTERMID
Specifies a terminal identifier that can be retrieved when the transaction is started.
RTRANSID
Specifies a transaction identifier that can be retrieved when the transaction is started.
SYSID
Specifies the ID of the remote application server that will receive the START request.
TERMID
Specifies the terminal name that will request the START command.
TIME
Specifies when the new task must be started. (Packed Decimal)
TRANSID
Specifies the transaction name that will executed with the START command.
USERID
Specifies the identification of the user under whose authority the started transaction is to run.
-
Only parsing is supported for ATTACH.
-
The following BATCH MTPBATCH command can be used to execute transactions instead of START.
CEMT STAR <transaction_name> [ <terminal_name> <ll data> ]
-
4. Task Control
An OSC application is usually initiated by a transaction request from a client. The transaction is processed by starting a task, which is similar to a thread. The difference between transaction and task is that while several users may invoke the same transaction, each initiates a separate task.
OSC application servers use multiple server processes to process tasks in parallel. Sometimes, a task may attempt to access a resource while this is being used by another task. In this case, OSC can control the sequence in which the tasks access the resource.
The following is an example.
-
Task T reserves resource R by issuing the ENQ command.
-
Another task, task U, issues the ENQ command to reserve resource R.
-
Task T is already using resource R, and therefore task U is queued.
-
Task T issues the DEQ command to release the resource.
-
Task U starts using resource R.
When a task ends, any resources reserved by it through the ENQ command will be automatically freed without issuing the DEQ command. The amount of time that the resource will be used can be specified with the ENQ command options. Currently, in OSC application servers, a resource reservation through the ENQ command can be made only with the resource’s name, and therefore the LENGTH option must be specified.
Task Control Commands
The following is a list of task control commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Releases a resource so that it can be used by other tasks. |
|
Requests for a reservation of a resource. |
|
Retrieves information about a specific user task. |
|
Retrieves a list of user tasks. User tasks are tasks associated with user-defined transactions or OSC-supplied transactions generally invoked by an operator. |
|
Retrieves information about the limits defined for a transaction class and the current activity in the class. |
|
Retrieves information about a specific transaction. |
|
Changes the limits about tasks managed in a specific transaction class. |
|
Changes some attributes set in a transaction definition. |
4.1. DEQ
Releases a resource so that it can be used by other tasks.
-
Syntax
EXEC CICS DEQ [option …] END-EXEC.
-
Options
Option Description RESOURCE
Specifies the name of the resource reserved by the ENQ command.
LENGTH
Specifies the length of the resource reserved with the resource’s name.
UOW|TASK|MAXLIFETIME
Specifies the same option that was specified when reserving the resource.
4.2. ENQ
Requests for a reservation of a resource.
-
Syntax
EXEC CICS ENQ [option …] END-EXEC.
-
Options
Option Description LENGTH
Specifies the length of the resource name.
NOSUSPEND
Raises an ENQBUSY condition when the resource is used by another user, without suspending the application program.
RESOURCE
Specifies the name of the resource to use.
UOW|TASK|MAXLIFETIME
-
UOW or TASK: Specifies the duration of resource usage by UOW or TASK.
-
MAXLIFETIME: Specifies the duration of resource usage with CVDA values.
-
4.3. INQUIRE TASK
Retrieves information about a specific user task.
-
Syntax
EXEC CICS INQUIRE TASK [option …] END-EXEC.
-
Options
Option Description ATTACHTIME
Returns an 8-byte packed decimal value that indicates the time at which a task was attached.
END
Ends browsing.
FACILITY
Returns the name of a facility associated with the initiation of a task where the facility is a transient data queue (TDQ), a terminal, or a system.
NEXT
Repeats the INQUIRE command. Only one resource definition is returned.
START
Starts browsing.
TASK
Specifies the 4-byte packed decimal sequence number of the inquiry target.
TRANSACTION
Returns the 4-character name of the transaction whose task is running.
PROGRAM
Returns the 8-character name of the program executed first in this task.
USERID
Returns the ID of the user associated with the task.
REMOTESYSTEM
Returns the 4-character name specified in the REMOTESYSTEM option of the TRANSACTION definition. If the transaction definition does not specify REMOTESYSTEM, it will return a blank value.
The following options are not supported: ACTIVITYID, BRFACILITY, BRIDGE, CMDSEC, CURRENTPROG, DB2PLAN, DTIMEOUT, DUMPING, FACILITYTYPE, IDENTIFER, INDOUBT, INDOUBTMINS, INDOUBTWAIT, IPFACILITIES, IPFLISTSIZE, ISOLATEST, PRIORITY, PROCESS, PROCESSTYPE, PROFILE, PURGEABILITY, REMOTENAME, RESNAME, RESSEC, ROUTING, RTIMEOUT, RUNAWAY, ROUTING, SCRNSIZE, STARTCODE, STORAGECLEAR, SUSPENDTIME, SUSPENDTYPE, SUSPENDVALUE, TASKDATAKEY, TASKDATALOC, TCB, TCLASS, TRACING, TRANCLASS, TRANPRIORITY, TRPROF, TWASIZE, and UOW.
4.4. INQUIRE TASK LIST
Returns a list of user tasks. User tasks are tasks that are associated with a user-defined transaction or an OSC-supplied transaction generally invoked by an operator.
-
Syntax
EXEC CICS INQUIRE TASK LIST [option …] END-EXEC.
-
Options
Option Description LISTSIZE
Returns the size of the list of user tasks.
SET
Returns the address of a list of 4-byte packed decimal task numbers.
SETTRANSID
Returns the address of a list of 4-byte transaction identifiers.
DISPATCHABLE
Indicates that a task ready to run is to be included in the task list.
RUNNING
Indicates that a currently running task is to be included in the task list.
SUSPENDED
Indicates that a suspended task is to be included in the task list.
4.5. INQUIRE TRANCLASS
Retrieves information about a specific transaction or the current activity in the class.
-
Syntax
EXEC CICS INQUIRE TRANCLASS [option …] END-EXEC.
-
Options
Option Description ACTIVE
Returns the current number of tasks in a class.
END
Ends browsing.
MAXACTIVE
Returns the maximum number of transaction classes that can run concurrently.
NEXT
Repeats the INQUIRE command. Only one resource definition is returned.
PURGETHRESH
Returns the maximum number of tasks that can be queued for an initial dispatch.
QUEUED
Returns the number of tasks that are queued for an initial dispatch.
START
Starts browsing.
TRANCLASS
Specifies an 8-character name of the inquiry target transaction class.
The following options are not supported: CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME and INSTALLUSRID.
4.6. INQUIRE TRANSACTION
Retrieves information about a specific transaction.
-
Syntax
EXEC CICS INQUIRE TRANSACTION [option …] END-EXEC.
-
Options
Option Description END
Ends browsing.
NEXT
Repeats the INQUIRE command. Only one resource definition is returned.
PROGRAM
Returns the name of the first program called by a task executing the transaction.
REMOTENAME
Returns an 8-character name of an OSC region specified in the REMOTESYSTEM option.
REMOTESYSTEM
Returns a 4-character name of an OSC region.
RESSEC
Returns an indicator that shows whether the resource-level security checking is to be performed for a task executing the transaction.
SHUTDOWN
Returns an indicator that shows whether the transaction can be executed during OSC shutdown by a task that processes non-requested input.
START
Starts browsing.
TCLASS
Returns the number of the transaction class that the transaction belongs to if the task belongs to a numbered class.
TRANCLASS
Returns an 8-character name of the transaction class that the transaction belongs to.
TRANSACTION
Specifies a 4-character name of the target transaction definition.
TWASIZE
Returns the size of the transaction work area (TWA).
STATUS
Returns the transaction status (either ENABLED or DISABLED).
The following options are not supported: BREXIT, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, CMDSEC, DEFINESOURCE, DEFINETIME, DTIMEOUT, DUMPING, FACILITYLIKE, INDOUBTWAIT, INSTALLAGENT, INSTALLTIME, INSTALLUSRID, ISOLATEST, PRIORITY, OTSTIMEOUT, PROFILE, PURGEABILITY, ROUTING, ROUTESTATUS, RTIMEOUT, RUNAWAY, RUNAWAYTYPE, SCRNSIZE, STORAGECLEAR, TASKDATAKEY, TASKDATALOC, TRACING, TRPROF, INDOUBT and INDOUBTMINS.
4.7. SET TRANCLASS
Changes the limits of tasks that can be managed in a specific transaction class.
-
Syntax
EXEC CICS SET TRANCLASS [option …] END-EXEC.
-
Options
Option Description TRANCLASS
Specifies the 8-character name of a transaction class to change.
MAXACTIVE
Specifies the maximum number of tasks to be run by a transaction class.
PURGETHRESH
Specifies the number greater than the maximum number of tasks that are queued for an initial dispatch by 1.
Only parsing is supported for END, NEXT, and START.
4.8. SET TRANSACTION
Changes some attributes set in a transaction definition.
-
Syntax
EXEC CICS SET TRANSACTION [option …] END-EXEC.
-
Options
Option Description SHUTDOWN
Specifies whether a transaction can be run during OSC shutdown by a task that processes an unsolicited input.
STATUS
Specifies whether the transaction is to be available for use.
TRANSACTION
Specifies a 4-character name of the transaction to be changed.
TCLASS
Specifies a fullword binary value of the transaction class to which the transaction will belong.
TRANCLASS
Specifies the 8-character name of the transaction class to which the transaction will belong.
-
DUMPING, PRIORITY, PURGEABILITY, RUNAWAY, RUNAWAYTYPE, and TRACING are not supported.
-
Only parsing is supported for END, NEXT, and START.
-
The following BATCH MTPBATCH command can be used to change STATUS instead of SET TRANSACTION.
CEMT SET TRAN<transaction_name> DIS | ENA
-
4.9. CREATE TRANSACTION
Dynamically creates transaction resources.
-
Syntax
EXEC CICS CREATE TRANSACTION [option …] END-EXEC.
-
Options
Option Description TRANSACTION
Specifies the four-letter name of the transaction to be created.
ATTRIBUTES
Specifies the properties of the transaction to be created.
ATTRIBUTES creates the properties in the System Definition as they are and creates them in the RTSD of OSC.
ATTRLEN
Specifies the length of ATTRIBUTES.
LOG
Sets to leave logs.
NOLOG
Sets not to leave logs.
LOGMESSAGE
Sets whether or not to leave logs.
LOG, NOLOG, and LOGMESSAGE are not supported options.
5. Dynamic Area Control
While OSC application servers allocate a fixed-size program local area (WORKING-STORAGE SECTION for COBOL programs) for application logic processing, it is often more efficient to use dynamically allocated areas instead. OSC application server supports dynamic memory allocation. The size of the memory allocated can be from one byte to the maximum integer value, or be limited according to the size of the system memory currently available.
By default, the allocated space is returned to the system at the end of the task that requested the space. However, if the SHARED option is specified, the space will not be returned after the task is completed and can be used to send and receive data between tasks. The SHARED option is different from the one used in CICS. For more information, refer to Memory Sharing between Tasks.
Dynamic Area Control Commands
The following is a list of dynamic area control commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Frees the space allocated by the GETMAIN command. |
|
Requests dynamic memory allocation. |
5.1. FREEMAIN
Allows the user to explicitly free the space allocated by the GETMAIN command.
-
Syntax
EXEC CICS FREEMAIN [option …] END-EXEC.
-
Options
Option Description DATA|DATAPOINTER
Set to one of the following.
-
DATA: Specifies the data area to be returned.
-
DATAPOINTER: Specifies the address of the memory to be returned.
-
5.2. GETMAIN
Requests dynamic memory allocation. The SHARED option controls when the allocated memory will be released. If SHARED is not specified, the memory will be automatically returned when the task is completed. If SHARED is specified, however, the memory must be released explicitly using the FREEMAIN command.
-
Syntax
EXEC CICS GETMAIN [option …] END-EXEC.
-
Options
Option Description FLENGTH|LENGTH
Specifies the size of the allocated memory.
INITIMG
Specifies a value to which the memory area will be initialized.
SET
Specifies the pointer reference to the address of the allocated memory.
SHARED
Specifies that the user must invoke FREEMAIN to release the allocated space.
-
BELOW is not supported.
-
Only parsing is supported for CICSDATAKEY, NOSUSPEND, and USERDATAKEY.
-
Memory Sharing between Tasks
When space is allocated by specifying the SHARED option of the GETMAIN command, the space can be used for transferring data between tasks.
Because each task running on the server is executed in a distinct server process, sending a memory address used by one task to another does not guarantee access to the same memory space by the destination task. To ensure that a task has access to the memory space used by another task, the memory address must be sent with the ENCODEMAIN and DECODEMAIN functions.
-
ENCODEMAIN
The ENCODEMAIN function receives two arguments: an absolute memory block address and an integer reference variable. It then converts the absolute memory block address into a relative memory block address and stores it in the integer reference variable. This relative memory address is then passed to another task so that it can access the information stored at that memory address.
The following example uses the ENCODEMAIN function.
. . . WORKING-STORAGE SECTION. 01 PTR USAGE IS POINTER. 01 OFFSET PIC S9(9) COMP. PROCEDURE DIVISION. . . . CALL "cics_encodemain" USING BY VALUE PTR BY REFERENCE OFFSET. . . . -
DECODEMAIN
The DECODEMAIN function receives two arguments: an integer reference variable and a relative memory block address. It then converts the relative memory block address back into an absolute memory block address and stores it as memory address reference. This absolute memory address allows the task to access the memory occupied by another task.
The following example uses the DECODEMAIN function.
. . . WORKING-STORAGE SECTION. 01 PTR USAGE IS POINTER. 01 OFFSET PIC S9(9) COMP. PROCEDURE DIVISION. . . . CALL "cics_decodemain" USING BY REFERENCE PTR BY VALUE OFFSET. . . .
6. Temporary Storage Queue (TSQ)
The Temporary Storage Queue (TSQ) allows data to be saved in a queue-type data structure.
TSQs are not prepared in advance by the OSC application server; instead, they are created when the first queue data record is written. Therefore, unlike most resources, the storage and recovery status properties of a queue can be defined when it is created.
-
Storage
One characteristic of the TSQ is that it is managed by another storage destination. Although TSQ can be managed by main or auxiliary storage, both storage locations are used in the same way by applications. The storage properties can be set by specifying the MAIN or AUXILIARY option for the EXEC CICS WRITEQ TS command, or by modifying the TSMODEL resource definition. Even if the default setting for a TSQ is AUXILIARY, it can be changed by setting the VALUE of the DFLTDEST key to MAIN, in the TSQ section of the osc.{servername} subject under OpenFrame Configuration.
Storage Characteristics MAIN
The contents of the queue are managed by the shared memory area specified in the server settings. Because it uses the main memory, this storage method provides much faster I/O performance than the AUXILIARY method.
The queue contents can be stored in the database instead of in the shared memory area, by setting the VALUE of the MAINDEST key to DB, in the TSQ section of the osc.{servername} subject under OpenFrame Configuration. This feature is available for multi-node clustering.
AUXILIARY
The queue contents are managed by two TSAM data sets: QINFO and QDATA. In this case, performance may be slower, but a transaction-level recovery is possible and all the existing data can remain intact. (Default value)
For more information about how to configure the osc.{servername} subject, refer to OpenFrame Configuration Guide.
-
Recovery status
The recovery status is defined in the TSMODEL resource definition; if this definition does not exist, recovery status is set to NON-RECOVERABLE. Since TSQ resources are subject to function shipping, they can be accessed by applications on a remote server.
Storage Applicable Queue Type RECOVERABLE
AUXILIARY
NON-RECOVERABLE
MAIN, AUXILIARY
For more information about TSQ resources, refer to Function Shipping.
TSQ and TSMODEL Commands
An application program can read, write, and delete TSQ data. A TSQ name can be up to 16 bytes long. To specify names up to 8 bytes long, use the QUEUE option. To specify names longer than 8 bytes, use the QNAME option.
The following is a list of TSQ and TSMODEL access commands. For more information about each command, refer to the respective section.
| Commands | Description |
|---|---|
Deletes a TSQ. All information in the TSQ will be deleted as well. |
|
Retrieves information about a TSQ. |
|
Retrieves resource information for TSMODEL. |
|
Reads data from a TSQ. |
|
Manages a TSQ. |
|
Writes data to a TSQ. |
6.1. DELETEQ TS
Deletes a TSQ and all of its contents. All information in the TSQ will be deleted as well.
-
Syntax
EXEC CICS DELETEQ TS [option …] END-EXEC.
-
Options
Option Description QUEUE
Specifies the queue name as a 1-8 byte character string.
QNAME
Specifies the queue name as a 1-16 byte character string.
SYSID
Specifies the SYSID for function shipping.
6.2. INQUIRE TSMODEL
Retrieves resource information about a TSMODEL.
-
Syntax
EXEC CICS INQUIRE TSMODEL [option …] END-EXEC.
-
Options
Option Description LOCATION
Returns the default storage location (AUXILIARY or MAIN) for queues that use the specified TSMODEL.
POOLNAME
Returns the name of the shared pool.
PREFIX
Returns a prefix for a TSMODEL.
REMOTEPREFIX
Returns a character string to be used as the prefix name of a remote system.
REMOTESYSTEM
Specifies a identifier of a remote system for which TSMODEL is defined.
TSMODEL
Specifies the name of a TSMODEL to view.
-
For more information about TSMODEL, refer to OpenFrame OSC Resource Definition Guide.
-
The following options are not supported: CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, EXPIRYINT, INSTALLAGENT, INSTALLTIME, INSTALLUSRID, RECOVSTATUS, SECURITYST.
-
6.3. INQUIRE TSQUEUE|TSQNAME
Retrieves information about a TSQ.
-
Syntax
EXEC CICS INQUIRE TSQUEUE|TSQNAME [option …] END-EXEC.
-
Options
Option Description FLENGTH
Returns the total length of the queue.
LASTUSEDINT
Returns the difference between the current time and the time when the queue was last accessed.
LOCATION
Returns the storage location (AUXILIARY or MAIN) of the TSQ.
MAXITEMLEN
Returns the length of the longest record in the queue.
MINITEMLEN
Returns the length of the shortest record in the queue.
NUMITEMS
Returns the total number of records in the queue.
RECOVSTATUS
Returns the recovery status.
TRANSID
Returns the ID of the transaction that created the TSQ.
TSQNAME
Specifies the queue name as a 1-16 byte character string.
TSQUEUE
Specifies the queue name as a 1-8 byte character string.
The following options are not supported: POOLNAME and SYSID.
6.4. SET TSQUEUE|TSQNAME
Manages a TSQ. Unlike DELETEQ TS, this command can delete a queue based on the time it was last used.
-
Syntax
EXEC CICS SET TSQUEUE|TSQNAME [option …] END-EXEC.
-
Options
Option Description ACTION
Specifies the CVDA value of the action to be taken. Currently only the DELETE value is supported.
DELETE
Specifies a queue to be deleted instead of CVDA value.
LASTUSEDINT
Deletes the TSQ if the amount of time since the TSQ was last used is over the specified value.
TSQNAME
Specifies the queue name as a 1-16 byte character string.
TSQUEUE
Specifies the queue name as a 1-8 byte character string.
The following options are not supported: POOLNAME and SYSID.
6.5. READQ TS
Reads data from a TSQ. Specifies the ITEM address to read records, or uses the NEXT option to read records sequentially. Data read from the queue are not deleted.
-
Syntax
EXEC CICS READQ TS [option …] END-EXEC.
-
Options
Option Description ITEM
Specifies the record address to read.
INTO
Specifies the location where the data to read will be stored.
LENGTH
Specifies the length of the storage of the data to read.
NEXT
Reads the next record sequentially.
NUMITEMS
Returns the number of records in the queue.
QNAME
Specifies the queue name as a 1-16 byte character string.
QUEUE
Specifies the queue name as a 1-8 byte character string.
SET
Specifies a pointer reference to contain the address of the data to be read. The storage is allocated by the system.
SYSID
Specifies the SYSID for function shipping.
6.6. WRITEQ TS
Writes data to a TSQ. If the specified TSQ does not exist, it will be dynamically created and store data.
-
Syntax
EXEC CICS WRITEQ TS [option …] END-EXEC.
-
Options
Option Description AUXILIARY
Stores TSQ to a data set.
FROM
Specifies the storage area to write data.
ITEM
Specifies the address to write data.
LENGTH
Specifies the length of the data to write.
MAIN
Stores TSQ in a memory.
NOSUSPEND
Specifies that the application program is not suspended if there is not enough memory to execute the WRITEQ TS command.
NUMITEMS
Returns the number of data records in the queue.
QUEUE
Specifies the queue name as a 1-8 byte character string.
QNAME
Specifies the queue name as a 1-16 byte character string.
REWRITE
Overwrites a record from a specific address. If this option is not specified, data records are added to the queue. If specified, an existing record is overwritten by a new record.
SYSID
Specifies the SYSID for function shipping.
7. Transient Data Queue (TDQ)
The Transient Data Queue (TDQ) is used for the following purposes:
-
Data communication between OSC applications
-
Temporary data storage while connecting OSC to another system
-
Data storage as UNIX file log type
There are five types of TDQ: intra-partition, extra-partition, log (functional), indirect and remote (administrative).
-
Intra-partition TDQ
To specify an intra-partition TDQ, enter INTRA in the TYPE field in the TDQ resource definition. This type of TDQ is used to send and receive data between OSC applications. The records stored in an intra-partition TDQ are managed through a TSAM data set.
In the resource definition for an intra-partition TDQ, the RECOVSTATUS option is set, meaning that if an error occurs, the TDQ can be recovered. A feature provided for intra-partition TDQs, the Automatic Transaction Initiation (ATI) function, automatically starts a specified transaction when the number of records in the queue reaches a number specified in the resource definition.
If ATIFACILITY is set to TERMINAL but the TERMINAL field has not been registered, automatic initiation will fail. If TERMINAL has been registered but no connection exists, the record will be queued in the internal scheduling queue. As soon as the terminal is reconnected, a new transaction will be initiated.
If the number of entries created by WRITEQ TD commands is greater than the specified TRIGGERLEVEL, a transaction will not be initiated. If this happens, you can use the oscadmin tool to remove the TDQ with the issue. If RECOVSTATUS is set to LOGICAL, ATI will not be invoked even if the number of entries created by WRITEQ TD command is greater than TRIGGERLEVEL. Instead, ATI will be invoked when executing the SYNCPOINT or RETURN command.
-
Extra-partition TDQ
This type of TDQ is used to send data from one system to another. To specify an extra-partition TDQ, set TYPE to EXTRA in the TDQ resource definition.
-
Log TDQ
An extra-partition TDQ can be used as a log in OSC application programs. Because they deal with frequent read and write operations, log TDQs have improved file I/O functions. To specify a log TDQ, set TYPE to LOG in the resource definition.
The OSC TDQ log server, one of the OSC auxiliary servers, processes the I/O commands sent to log TDQs. When an application program writes data to the TDQ, log data will be appended to a file with the same name as DDNAME. This file is stored in the SPOOL directory named after the server. Then, the OSC TDQ log server buffers the stored data and writes it all to the file at once, minimizing the amount of write operations and lessening the load on the system.
Communication between the application server and the OSC TDQ log server uses the TCP/IP protocol.
-
Indirect TDQ
Indirect TDQs are used for system management. An indirect TDQ points to another queue (either intra-partition, extra-partition, remote, or another indirect TDQ) so that all requests directed to the indirect TDQ are routed to the other queue. To specify this type of TDQ, set TYPE to INDIRECT in the TDQ resource definition and enter the name of the other queue in the INDIRECTNAME element.
-
Remote TDQ
Application programs may need to access a TDQ that resides on a remote application server. To specify a TDQ that will be used as the target of function shipping commands, set the TYPE to REMOTE in the resource definition. Function Shipping is described in detail in Function Shipping. If set to REMOTE, nothing is specified to the TYPE of the resource definition and a remote application server is specified to REMOTESYSTEM.
TDQ Access Commands
Although methods of accessing a TDQ are slightly varying depending on the TDQ type, there are common commands to delete, read and write data from and to a TDQ, such as DELETEQ TD, READQ TD, WRITEQ TD.
The following is a list of TDQ access commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Deletes a TDQ. |
|
Inquires information about TDQ. |
|
Reads records from a TDQ. |
|
Changes some attributes of a TDQ. |
|
Writes records to a TDQ. |
|
Creates a TDQ dynamically. |
|
Discards a dynamically created TDQ. |
7.1. DELETEQ TD
Deletes an intra-partition, indirect, or remote TDQ.
-
Syntax
EXEC CICS DELETEQ TD [option …] END-EXEC.
-
Options
Option Description QUEUE
Specifies the name of the queue to delete.
SYSID
Specifies the ID of the system where the remote queue is located.
7.2. INQUIRE TDQUEUE
Inquires information about a specific TDQ.
-
Syntax
EXEC CICS INQUIRE TDQUEUE [option …] END-EXEC.
-
Options
Option Description ATIFACILITY
Returns an indicator that shows whether the queue has a terminal or a session associated with it.
BLOCKFORMAT
Returns an indicator that shows whether a data set associated with the queue is in block record format.
BLOCKSIZE
Returns the length of the block in bytes.
DDNAME
Returns an 8-character identifier that can refer to the data set used in the startup JCL.
DISPOSITION
Returns the status of an associated data set.
DSNAME
Returns a name, ranging from 1-44 bytes, that represents an associated DUMMY data set.
ENABLESTATUS
Returns an indicator that shows whether an application program can access the queue.
END
Ends browsing.
INDIRECTNAME
Returns a 4-character name of the queue that the indirect queue points to.
NEXT
Repeats the INQUIRE command. Only one resource is returned.
OPENSTATUS
Returns an indicator that shows whether the queue is open or not.
PRINTCONTROL
Returns an indicator that shows the type of print control defined for the queue.
RECORDFORMAT
Returns an indicator that shows whether the queue contains a fixed-length record or a variable-length record.
RECORDLENGTH
Returns the record length for queues. If the queue type is other than EXTRA, -1 is returned.
RECOVSTATUS
Returns the type of recovery defined for the queue.
REMOTENAME
Returns an 8-character name of the OSC region specified in the REMOTESYSTEM option.
REMOTESYSTEM
Returns a 4-character name of the OSC region.
SYSOUTCLASS
Returns a character that indicates the class property of the SYSOUT data set. This option returns a blank if DSNAME is used.
START
Starts browsing. No data is returned.
TRIGGERLEVEL
Returns the number of items on the queue to be reached before automatic transaction initiation (ATI).
TYPE
Returns the type of the queue.
TDQUEUE
Specifies a 4-character name of the transient data queue.
The following options are not supported: ATITERMID, ATITRANID, ATIUSERID, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DATABUFFERS, DEFINESOURCE, DEFINETIME, EMPTYSTATUS, ERROROPTION, INDOUBT, INDOUBTWAIT, INSTALLAGENT, INSTALLTIME, INSTALLUSRID, IOTYPE, MEMBER, NUMITEMS, and REWIND.
7.3. READQ TD
Reads records from an intra-partition TDQ, indirect TDQ, or remote TDQ.
-
Syntax
EXEC CICS READQ TD [option …] END-EXEC.
-
Options
Option Description INTO
Specifies the location where the data to read will be stored.
LENGTH
Specifies the maximum length of the storage of the INTO data to be read.
NOSUSPEND
Specifies that a task is not suspended until the queue becomes available if an application program tries to read the queue being used for output.
QUEUE
Specifies the queue name.
SET
Specifies a pointer reference that will contain the address of the data to be read.
SYSID
Specifies the ID of the system where the remote queue is located when reading from a remote TDQ.
7.4. SET TDQUEUE
Changes some attributes of TDQ.
-
Syntax
EXEC CICS SET TDQUEUE [option …] END-EXEC.
-
Options
Option Description ATIFACILITY
Specifies whether the queue is to have a terminal or session associated with it.
ENABLESTATUS
Specifies whether an application can access the queue.
-
DISABLED
-
ENABLED
OPENSTATUS
Specifies whether to open or close a data set associated with the queue.
-
CLOSED
-
OPEN
TDQUEUE
Specifies a 4-character name of the transient data queue.
TRIGGERLEVEL
Specifies a fullword binary value that represents the number of items that have to be reached to trigger an automatic transaction initiation. To disable ATI, specify 0.
-
The following options are not supported: ATITERMID, ATITRANID and ATIUSERID.
-
Only parsing is supported for END, NEXT and START.
-
The following BATCH MTPBATCH command can be used to change OPENSTATUS instead of SET TDQUEUE.
CEMT SET TD<TDQ_name> CLOSED | OPEN
-
7.5. WRITEQ TD
Writes records to any type of TDQ. This command is supported for all TDQ types.
-
Syntax
EXEC CICS WRITEQ TD [option …] END-EXEC.
-
Options
Option Description FROM
Specifies the data storage where the source data is stored.
LENGTH
Specifies the length of the data to write.
QUEUE
Specifies the queue name.
SYSID
When writing to a remote TDQ, this specifies the ID of the system where the remote queue is located.
7.6. CREATE TDQUEUE
Creates an extra-partition TDQ dynamically.
-
Syntax
EXEC CICS CREATE TDQUEUE [option …] END-EXEC.
-
Options
Option Description TDQUEUE
Specifies a 4-character name of the temporary data queue to create.
ATTRIBUTES
Specifies attributes of the temporary data queue to create. Specify the attributes in System Definition as they are to create them in OSC RTSD. The following ATTRIBUTES are currently available.
-
TYPE ( { EXTRA } )
-
TYPEFILE ( { INPUT | OUTPUT | RDBACK } )
-
DISP ( { SHR | OLD | MOD } )
-
DD or DDNAME ( ddname )
-
DSN or DSNAME ( dsname )
ATTRLEN
Specifies the length of ATTRIBUTES.
LOG
Creates logs.
NOLOG
Does not create any logs.
LOGMESSAGE
Specifies whether to create logs.
The following options are not supported: LOG, NOLOG and LOGMESSAGE.
-
8. Channels and Containers
Channels and containers are structures for sending and receiving data between application programs. A container is much like a COMMAREA with a specified name, and a channel is a set of containers.
The OSC application programs generally use the COMMAREA area, which is limited to 32 KB of storage, to send and receive data. However, channels and containers, which have no storage limits, are more flexible methods of transferring data.
Channels and containers:
-
can be accessed only by the program that created them or a program that receives them with a LINK or XCTL command. The set of containers that is passed to the active program is called the current channel.
-
are automatically deleted, along with the data they contain, after the program terminates.
-
cannot be recovered in the event of a failure, including the data they contain.
Channel and Container Commands
The following is a list of channel and container commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Deletes a container and the data it contains. |
|
Reads data from a container. |
|
Moves a container from one channel to another. |
|
Stores data in a container of a specific channel. |
8.1. DELETE CONTAINER
Deletes a container and the data it contains.
-
Syntax
EXEC CICS DELETE CONTAINER [option …] END-EXEC.
-
Options
Option Description CHANNEL
Specifies the channel to which the container belongs to. If the CHANNEL option is not specified, the current channel will be selected.
CONTAINER
Specifies the name of the container to delete.
8.2. GET CONTAINER
Reads data from a container. If CHANNEL option is not specified, data will be read from the current channel.
-
Syntax
EXEC CICS GET CONTAINER [option …] END-EXEC.
-
Options
Option Description CONTAINER
Specifies the name of a container.
CHANNEL
Specifies the channel where the container is located. If the CHANNEL option is not specified, the current channel will be selected.
FLENGTH
Specifies the length of the data to read.
INTO
Specifies a data area where data will be stored.
SET
Specifies a pointer reference that will contain the address of the data to be read.
Only parsing is supported for NODATA.
8.3. MOVE CONTAINER
Copies a container from one channel to another or changes the name of a container in a channel. After a copy of a container is made in another channel, the original container will be removed from the original channel. If the CHANNEL and TOCHANNEL options are not specified, the current channel will be selected by the server. The MOVE CONTAINER command can be used to move a container from one channel to another or to rename a container in a channel.
-
Syntax
EXEC CICS MOVE CONTAINER [option …] END-EXEC.
-
Options
Option Description AS
Specifies the new name of the container.
CHANNEL
Specifies the channel which the container belongs to.
CONTAINER
Specifies the name of the container to move.
TOCHANNEL
Specifies the name of the destination channel.
Only parsing is supported for FROMACTIVITY, FROMPROCESS, TOACTIVITY, and TOPROCESS.
8.4. PUT CONTAINER
Stores data in a container.
-
Syntax
EXEC CICS PUT CONTAINER [option …] END-EXEC.
-
Options
Option Description APPEND
Specifies to append the data to the existing data in the container.
BIT
Bit data. This is the default data type unless FROMCCSID is specified.
CONTAINER
Specifies the container name.
CHANNEL
Specifies the channel of the container. If the CHANNEL option is not specified, the current channel will be selected.
CHAR
Specifies a character data.
DATATYPE
Specifies the type of the data.
FLENGTH
Specifies the length of the data.
FROM
Specifies the location to read the data from.
FROMCCSID
Specifies the current CCSID.
9. Journal Control
A journal can store any data that helps a system recover from some event or data changes, as needed by the user. For example, database changes or transaction history can be recorded in a journal. The WRITE and WAIT commands, which create a journal record and synchronize the journal results, are used by CICS to manage the journal..
OSC supports the WRITE command, but not WAIT. In order to synchronize journal results, the user must specify the WAIT option of a WRITE command.
The following BATCH MTPBATCH command can be used to write all the current records to a log stream before handling a stream.
CEMT SET JO<journal_name> FLUSH
Journal Control Commands
The following is a list of journal control commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Creates a journal record. |
|
Returns information about a specific journal model that has been installed, to obtain the corresponding log stream name. |
|
Creates a journal record. This is the same as JOURNAL but with different options. |
|
Creates a journal record. Specifies a journal number, while WRITE JOURNALNAME specifies a journal name. |
9.1. JOURNAL
Creates a journal record. The JOURNAL command is provided only for compatibility with earlier versions, and it is recommended to use the WRITE JOURNALNAME command instead.
-
Syntax
EXEC CICS JOURNAL [option …] END-EXEC.
-
Options
Option Description FROM
Specifies the data area where the user data is stored.
JFILEID
Specifies a journal ID. A journal ID can range from 1 to 99.
JTYPEID
Specifies the origin of the journal record. This is a 2 byte ID.
LENGTH
Specifies the length of the user data.
PREFIX
Specifies the path to which the prefix data is stored.
PFXLENG
Specifies the length of the prefix data.
WAIT
Specifies whether synchronization will occur when creating a journal record.
Only parsing is supported for NOSUSPEND, REQID, and STARTIO.
9.2. INQUIRE JOURNALMODEL
Returns information about a specific journal model that has been installed, to obtain the corresponding log stream name.
-
Syntax
EXEC CICS INQUIRE JOURNALMODEL [option …] END-EXEC.
-
Options
Option Description END
Ends browsing.
JOURNALMODEL
Returns a 1-8 character name of an installed journal model.
JOURNALNAME
Returns a 1-8 character name of a journal.
NEXT
Repeats the INQUIRE command. Only one resource is returned.
STREAMNAME
Returns the log stream name associated with JOURNALMODEL.
START
Starts browsing.
TYPE
Returns the log stream type.
The following options are not supported: CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME and INSTALLUSRID.
9.3. WRITE JOURNALNAME
Creates a journal record.
-
Syntax
EXEC CICS WRITE JOURNALNAME [option …] END-EXEC.
-
Options
Option Description FROM
Specifies the path to which the user data is stored.
FLENGTH
Specifies the length of the user data.
JOURNALNAME
Specifies the journal name.
JTYPEID
Specifies the origin of the journal record. This is a 2 byte ID.
PREFIX
Specifies the path to which the prefix data is stored.
PFXLENG
Specifies the length of the prefix data.
WAIT
Specifies whether synchronization will occur when creating a journal record.
Specifies whether synchronization will occur when creating a journal record.
9.4. WRITE JOURNALNUM
Creates a journal record. The WRITE JOURNALNUM command is provided for compatibility with earlier versions; WRITE JOURNALNAME is recommended instead.
-
Syntax
EXEC CICS WRITE JOURNALNUM [option …] END-EXEC.
-
Options
Option Description FROM
Specifies the path to which the user data is stored.
FLENGTH
Specifies the length of the user data.
JOURNALNUM
Specifies a journal ID that ranges from 1 to 99.
JTYPEID
Specifies the origin of the journal record. This is a 2 byte ID.
PREFIX
Specifies the path to which the prefix data is stored.
PFXLENG
Specifies the length of the prefix data.
WAIT
Specifies synchronous journal output that cause the requesting task to wait until the journal output has been completed.
Only parsing is supported for NOSUSPEND, REQID and STARTIO.
10. Document Control
Allows the user to document specific data. The users can use the documented data by specifying DOCTOKEN in commands that support DOCTOKEN.
Document Control Command
The following is a list of document control commands. For more information about each command, refer to the respective section.
| Command | Description |
|---|---|
Creates a document. |
|
Inserts text, bookmarks or documents to a document. |
10.1. DOCUMENT CREATE
Creates a document.
-
Syntax
EXEC CICS DOCUMENT CREATE [option …] END-EXEC.
-
Options
Option Description DOCTOKEN
After creating the document, issues TOKEN for reuse and returns it.
FROM
Specifies the data to use when creating a document.
HOSTCODEPAGE
Specifies CODEPAGE of the document.
LENGTH
Specifies the size of data to use.
LISTLENGTH
Specifies the length of the symbol list.
SYMBOLLIST
Specifies a buffer which contains a symbol list. A symbol list is a character string consisting of one or more symbol definitions separated by ampersands.
TEMPLATE
Specifies the 48-byte name of a template.
TEXT
Specifies a buffer of data which is to be used as the contents of the new documnet being created.
10.2. DOCUMENT INSERT
Inserts text, bookmarks or documents to a document.
-
Syntax
EXEC CICS DOCUMENT INSERT [option …] END-EXEC.
-
Options
Option Description DOCTOKEN
Adds content to a returned document.
TEXT
Specifies the text to add.
TEMPLATE
Specifies the 48-byte name of a template.
LENGTH
Specifies the length of the text to add.
FROMDOC
Specifies DOCTOKEN of the document to add.
BOOKMARK
Specifies the name of the bookmark to add.
AT
Specifies the location to add TEXT, DOCUMENT and BOOKMARK. A BOOKMARK that has been previously added becomes the target of AT.
If the AT options is omitted, the specified content is added to the bottom of the document and if not, the content is added to the top of the document, by default. Otherwise, AT can be specified through BOOKMARK.