This chapter documents the function and syntax of each host command used in the CA Verify for CICS Host Command Environment. The commands are presented in alphabetical order according to command name.
This section contains the following topics:
When CA Verify for CICS commands start or use sessions, start or end session traces, queue or pull queued data or perform other command functions, by default, they anchor or use resources anchored to the CA Verify for CICS port on which the issuing exec is executing, and session commands return session information using the simple session variable names defined in CA Verify for CICS REXX Variables.
The command:
Compound session variable names, like PTEBUFF.1, have a REXX stem that is a defined simple session variable name and a tail that is the accessed port number.
Examples:
" ACCESS EXECPORT " " ACCESS NEWPORT " " ACCESS 3 " " ACCESS &port "
Format:
ACCESS ( EXECPORT | * | port | NEWPORT | FREEPORT | LASTPORT ) ( LOCK )
Instructs subsequent commands to anchor or use resources anchored to the port on which the exec is executing, and instructs session commands to return information using simple session variable names.
Where port is either a port number or a REXX variable name, coded with a leading ampersand, that contains a port number, instructs subsequent commands to anchor or use resources anchored to the specified port, and instructs session commands to return information using compound session variable names.
Assigns an unused port number, instructs subsequent commands to anchor or use resources anchored to the assigned port, and instructs session commands to return information using compound session variable names.
Locates a port on which no exec, session, session trace, data queue or lock is active, or assigns an unused port number, instructs subsequent commands to anchor or use resources anchored to the located or assigned port, and instructs session commands to return information using compound session variable names.
Identifies the port that was last accessed by any exec running on the current exec port, instructs subsequent commands to anchor or use resources anchored to the identified port, and instructs session commands to return information using compound session variable names.
Can be specified to lock the accessed port. When a port is locked, an UNLOCK command must be issued before port resources can be created or used by an exec running on any port other than the port that holds the lock.
At the completion of an ACCESS command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes ACCESS command return codes and default REXX conditions that may be raised for some conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
CANCEL |
24 |
HALT |
Cancel command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The ATTACH command creates a new z/OS task and REXX Language Processor environment, anchors the environment to the CA Verify for CICS port being accessed by the exec when the ATTACH command is issued, and executes a specified exec in the new REXX Language Processor Environment.
The difference between calling an exec and attaching an exec is that the REXX CALL instruction completes and the calling exec resumes execution only when the called exec returns to the calling exec. However, the ATTACH command completes and the attaching exec resumes execution at the same time that the attached exec begins execution. Called and calling execs run one at a time, while attached and attaching execs run at the same time.
Examples:
" ATTACH EXEC &execname "," &arg1 'arg2' "
" ATTACH EXEC subexec 'logon' "" &sysid &uid &code "
Format:
ATTACH EXEC execname ( arg1 . . . arg20 ) ( EXECDD execdd ) ( SAYDD saydd ) ( SAYDEST saydest ) ( MSGDEST msgdest )
A required keyword which indicates that the value that follows is the name of the exec to be attached.
The name of the REXX exec to be attached. It may be the actual exec name, a literal whose value is the exec name, or a variable name coded with a leading ampersand that contains the exec name (for example, &execname).
Up to 20 arguments to be passed to the attached exec. Each argument may be a literal value enclosed in single or double quotes, or may be a variable name, coded with a leading ampersand that contains an argument value (for example, &arg).
Note: An attached exec may use a REXX ARG instruction to assign argument values to corresponding variables specified by REXX ARG instruction. ARG instruction variable names are separated by commas.
An optional keyword which indicates that the value that follows is the DD name of the REXX library(s) from which the attached exec, and other execs, are to be loaded into the REXX Language Processor Environment created by the ATTACH command.
The exec library DD name from which execs are loaded. It may be the actual DD name, a literal whose value is the DD name, or a variable name coded with a leading ampersand that contains the exec library DD name (for example, &execdd). If an EXECDD is not specified, execs are loaded from the exec libraries used in the first REXX Language Processor Environment in an address space that uses CA Verify for CICS commands for REXX, usually from SYSEXEC and/or SYSPROC.
An optional keyword which indicates that the value that follows is the DD name to which REXX SAY messages are to be written in the REXX Language Processor Environment created by the ATTACH command. The SAYDD keyword option is subject to system options, described below, that control REXX message management options.
The DD name to which REXX SAY messages are to be written. It may be the actual DD name, a literal whose value is the DD name, or a variable name coded with a leading ampersand that contains the DD name (for example, &saydd).
A null-valued variable may be specified as a saydd to request allocation of a new message dataset using a unique system-assigned DD name, and that the assigned name is to be returned to the attaching exec in the specified saydd variable.
If a specified saydd is already allocated when an ATTACH command is executed, the allocated dataset is used in the new REXX Language Processor Environment as a message dataset. If a saydd that was not allocated by CA Verify for CICS is specified for two or more attached execs that run concurrently, the user must insure that the allocated dataset can be used as a shared message destination by the REXX Language Processor Environments created to run the attached execs.
An optional keyword which indicates that the value that follows is to be allocated as the destination of REXX SAY messages, if the specified or default SAYDD is not allocated when the ATTACH command is executed. The SAYDEST keyword option is subject to system options, described below, that control REXX message management options.
The SAYDEST destination value. It may be a JES SYSOUT class, an asterisk, *, to specify the default SYSOUT class for the address space, or may be the keyword, TERMINAL to send REXX SAY messages to a TSO terminal. saydest may be the actual JES SYSOUT class or the TERMINAL keyword, may be a literal whose value is the SAY message destination, or may be variable name coded with a leading ampersand that contains the SYSOUT class or TERMINAL keyword (for example, &saydest).
An optional keyword which indicates that the value that follows is the destination of REXX error messages issued while processing execs in the REXX Language Processor Environment created by the ATTACH command. The MSGDEST keyword option is subject to system options, described below, that control REXX message management options.
A REXX error message destination identified by the MSGDEST keyword. Specify one of the following destination keywords:
Msgdest may be a destination keyword, may be a literal whose value is a destination keyword, or may be a variable name coded with a leading ampersand that contains a REXX message destination keyword (for example, &msgdest).
Note: The number of REXX execs that may be attached is limited by the REXX Language Processor Environment limit contained in the TSO/E REXX environment table, IRXANCHR. IBM publication, TSO/E REXX/z/OS Reference, explains how to change the REXX environment limit.
All REXX Language Processor Environments in which CA Verify for CICS commands are used are anchored to a CA Verify for CICS port. When commands are used by an exec running in a REXX environment not created by CA Verify for CICS, the environment is anchored to a port when the first command is issued. Only one REXX Language Processor Environment may be anchored to a port. The ATTACH command creates a new REXX Language Processor Environment and anchors the environment to the port being accessed by an exec anchored to the port. Before using the ATTACH command, an exec must use the CA Verify for CICS ACCESS command to access a NEWPORT, a FREEPORT, or to access a specific port that is not already associated with a REXX Language Processor Environment.
An attached exec may ADDRESS VERIFY and issue commands for REXX.
REXX Language Processor Environments created by the ATTACH command are not integrated into TSO. Attached execs may not use TSO and ISPF commands that are supported only in REXX Language Processor Environments that are integrated into TSO. However, execs that operate correctly when attached in a TSO address space may also be attached and operate correctly when IRXJCL is used to execute an exec as a batch job or when they are attached in other non-TSO address spaces.
Attaching Asynchronous Exec Tasks and Queues and Intertask Communication describe applications of the ATTACH command and other CA Verify for CICS commands designed for use by execs that run in a multi-task environment.
The operation of and default values of the SAYDD, SAYDEST and MSGDEST keyword options are subject to CA Verify for CICS system options that allow an installation to specify REXX message management options for each named address space in which CA Verify for CICS commands for REXX are used. The name of an address space is defined by the REXX parameters module used to initialize REXX Language Processor Environments.
At the completion of an ATTACH command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes ATTACH command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The CANCEL command causes the REXX HALT condition to be raised for the exec that is active on the port being accessed by the issuing exec.
Example:
" CANCEL "
Format:
CANCEL
When the CANCEL command is executed, if an exec is active on the port being accessed, then cancellation of the exec is scheduled. The REXX HALT condition is subsequently raised when the cancelled exec recognizes the request following the execution of any CA Verify for CICS command.
When the CANCEL command is executed, if a CA Verify for CICS command is currently executing within the cancelled exec, and if the command is waiting for the completion of an event that is under CA Verify for CICS control, then the wait for the completion of the event is interrupted immediately. The REXX HALT condition is raised when the interrupted command ends.
If an exec is not active on the port being accessed when a CANCEL command is executed, then no action is performed, but the command is considered to have completed without error.
At the completion of a CANCEL command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes CANCEL command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The DELAY command delays execution of an exec for a specified amount of time, but allows outbound session traffic to flow on the session anchored to the port being accessed by the exec, during the delay.
Examples:
" DELAY 3200 "" DELAY PERCENT 50 "
Format:
DELAY hhmmssth | ( PERCENT percent )
A delay time interval, expressed in hours (hh), minutes (mm), seconds (ss) and tenths and hundredths of seconds (th). A delay time interval may be specified using a REXX variable, coded with a leading ampersand, that contains the interval in the format hhmmssth.
An optional keyword, which specifies that delay times specified by DELAY commands subsequently executed by execs that run on the CA Verify for CICS port on which a DELAY PERCENT command is executed, are to be factored by the specified percent.
May be an integer value from zero to 999, or may be a variable field that contains an integer from zero to 999. It is the percent of specified delay times to be used when DELAY commands are subsequently executed.
DELAY commands created by recording a session as a REXX exec capture the elapsed time, often called think time, that it took for a user to press enter or another key that sends data, after receiving the preceding message from the online system. When a DELAY command is executed, exec execution is delayed until the recorded or specified delay time elapses, simulating the think time delays that occur when people use terminals, and causing a session produced by a recorded exec to proceed at the same speed as the captured session.
The speed of execs that issue DELAY commands may be controlled using a DELAY command that specifies a delay PERCENT. When a DELAY PERCENT command is executed that specifies a percent less than 100, exec execution is delayed only for a percent of the time specified by each subsequent DELAY command and the exec runs faster. When a percent greater than 100 is specified, delays are longer than the delay times specified by subsequent DELAY commands, causing the exec to run slower.
Because DELAY PERCENT applies to all execs that run on a CA Verify for CICS port, an exec that calls other execs can control the speed of the called execs by issuing a DELAY PERCENT command.
At the completion of a DELAY command, updated information is returned in session variables that reflects any outbound message(s) received during a delay. Refer to CA Verify for CICS REXX Variables for a description of the information returned in session variables.
At the completion of a DELAY command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes DELAY command return codes and REXX conditions that are raised by default when some CA Verify for CICS conditions occur.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
TIMEOUT |
8 |
|
Timed out waiting for response |
|
LOGOFF |
16 |
|
Session Ended |
|
ENDTRACE |
20 |
HALT |
Trace abended (ie., SD37) |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The DELETEQ command is used to delete the entire data queue that is anchored to the port being accessed by the issuing exec.
Example:
" DELETEQ "
Format:
DELETEQ
At the completion of a DELETEQ command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes DELETEQ command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
LOCKOUT |
0 |
|
Timed out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The ENDTRACE command ends a session trace anchored to the port being accessed by an exec when the command is issued. A session trace is started by the TRACE command.
Example:
" ENDTRACE "
Format:
ENDTRACE
At the completion of an ENDTRACE command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes ENDTRACE command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
LOCKOUT |
0 |
|
Timed out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The HANDLE command activates or inactivates automatic handling of named session events when they occur during the processing of subsequently executed CA Verify for CICS session commands.
Examples:
" HANDLE turnaround off "" HANDLE outbound off "
Format:
HANDLE event option
One of the keywords, TURNAROUND or OUTBOUND, that names the session event for which handling is being specified.
One of the keywords, ON or OFF, that specifies whether automatic handling of the named event is to be activated or inactivated.
The HANDLE command TURNAROUND keyword refers to the point in a session that occurs when a TYPE command has sent input to an online system and changes the session direction to outbound. By default or when HANDLE TURNAROUND ON is specified, the TYPE command automatically waits for and receives the online system response to a terminal input. When HANDLE TURNAROUND OFF is specified, subsequent TYPE commands do not wait for the online system response but rather complete immediately after the session direction is changed to outbound. HANDLE TURNAROUND OFF makes the TYPE command a send-only operation. After executing a TYPE command while TURNAROUND handling is off, an exec must eventually use the INVITE command to receive the online system response to the input sent by a TYPE command.
The HANDLE command OUTBOUND keyword refers to the point in a session at which an outbound message has been received from an online system that does not free the terminal keyboard, but rather leaves the session in the outbound state. By default or when HANDLE OUTBOUND ON is specified, when a CA Verify for CICS session command receives a message from an an online system that leaves the session in the outbound state, then CA Verify for CICS automatically waits for and receives the next message sent by the online system. When HANDLE OUTBOUND OFF is specified, TYPE and INVITE commands that receive messages that leave the session in the outbound state complete following the receipt of each message, whether or not the terminal keyboard is freed. After executing a TYPE or INVITE command that ends a message, is received, and leaves the session in an outbound state while OUTBOUND handling is off, an exec must eventually use the INVITE command to receive the next message sent by the online system.
When HANDLE commands are used to obtain control of outbound messages, and when TYPE and INVITE commands complete while the virtual terminal keyboard is not free, an exec must be aware of the state of a session and act accordingly. Specifically, a TYPE command is valid only while the keyboard is free. An INVITE command must eventually be issued to receive an online system message while the keyboard is locked. Execs that choose to handle outbound message flows may use CA Verify for CICS-defined variable fields PTEKB or PTESTATE to determine the state of a session and to decide whether TYPE commands are valid or INVITE commands are required. Refer to CA Verify for CICS REXX Variables for descriptions of PTEKB or PTESTATE and the possible values of the variable fields.
At the completion of a HANDLE command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the HANDLE command. The following table describes HANDLE command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The INVITE command receives any message sent by an online system within a specified time interval. It may be used to receive a message that is sent by an online system while the terminal keyboard is free, or to receive messages when the state of a session is outbound after using HANDLE OUTBOUND, HANDLE TURNAROUND, or WAIT time ON RESPONSE commands.
Examples:
" INVITE 1000 "" INVITE &invtime "
Format:
INVITE hhmmssth
An optional time interval, expressed in hours (hh), minutes (mm), seconds (ss) and tenths and hundredths of seconds (th).
The INVITE command is used to receive a message at a virtual terminal that is anchored to the port that is being accessed by an exec. The LOGON command allocates and anchors a virtual terminal to an accessed port and uses the terminal to start a session.
A CA Verify for CICS LOGON command completes immediately after a session is started. The virtual terminal keyboard is always free at the beginning of a session, as is the keyboard on a real terminal. While it is true that a terminal keyboard is free before the first message is sent on a new session, this is seldom noticed by a person. After starting a session, most online systems send a message to the terminal. People are naturally patient and wait until they see the expected message.
REXX execs that use CA Verify for CICS host commands to start and use terminal sessions with an online system take the place of a terminal operator and must do the things that a person would do if a session is to flow smoothly. The INVITE command allows an exec to wait for an expected message, as a person would. At the start of a session, if an online system sends one or more initial messages, an exec must execute one or more INVITE commands to allow the online system to send the messages.
After receiving a terminal input, some online systems and applications send a message that frees the terminal keyboard immediately after receiving the terminal input. Then, at a later time, the online system sends another message that a terminal user sees as the response to the terminal input. Like a signon prompt sent at the start of a session, the unnoticed free keyboard situation does not cause a problem because the terminal operator is patient and waits for the expected message. A TYPE command ends when an online system message frees the terminal keyboard. If an online system sends a response that frees the terminal keyboard before sending the response message the user is expecting, then an exec must add patience by executing INVITE commands whenever it is necessary to wait for the delayed response.
Because people do not notice some free keyboard situations, it is sometimes difficult to determine when to code INVITE commands. One way to determine if an INVITE is needed is to examine a CA Verify for CICS test stream for the online system or application in question. A test stream may be created using option L, Log a Test Stream, on the CA Verify for CICS menu.
Browse the test stream, stopping at the record selection list. Enter the PROFILE command, select the WCC category, press PF3 to return to the record selection list. Paying attention to the OP column (operation), scroll forward through the record selection list. If you see two or more output operations in a row - without input operations between each output, an INVITE may be needed. Any WCC value greater than C1 unlocks the keyboard. If the keyboard is unlocked before the last output in the sequence, an INVITE is recommended after each output after the keyboard was unlocked.
At the completion of an INVITE command, updated information is returned in session variables, as documented in CA Verify for CICS REXX Variables.
At the completion of an INVITE command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes INVITE command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
TIMEOUT |
8 |
|
Timed out waiting for response |
|
LOGOFF |
16 |
|
Session ended |
|
ENDTRACE |
20 |
HALT |
Trace abended (ie., SD37) |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The LOCK command locks the port that is being accessed by an exec and all resources anchored to the port.
The ACCESS command may also be used to lock a port when it is accessed.
While a port is locked, resources anchored to the port may be used only by execs that run on same port as the exec that issued the LOCK command. If an exec running on any other port issues a CA Verify for CICS command that uses resources anchored to the locked port, the command is delayed until the port is unlocked.
The UNLOCK command is used to unlock a locked port.
Example:
" LOCK "
Format:
LOCK
Note: Refer to Sharing Resources with Attached Execs for more information about locks and uses of locks.
At the completion of an LOCK command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes LOCK command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
LOCKOUT |
0 |
|
Timed out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The LOGOFF command ends a session that was started using the LOGON command.
Example:
" LOGOFF "
Format:
LOGOFF
The LOGOFF command ends the session anchored to the port being accessed by an exec when the command is executed.
When the LOGOFF command is used to end a session, the online system sees the session termination in exactly the same way that it sees a session termination that occurs when a user presses the SYSREQ key on a real terminal keyboard, then enters the command LOGOFF, to request that VTAM terminate the active application session.
The preferred way to end a session is to issue a TYPE command that enters a particular online system's logoff command or transaction. Entering a logoff transaction may be required for some online systems to give the online system an opportunity to clean up resources that were allocated when the user signed on.
At the completion of a LOGOFF command, all session variables described in CA Verify for CICS REXX Variables are dropped.
At the completion of a LOGOFF command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes LOGOFF command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
ENDTRACE |
20 |
HALT |
Trace abended (ie., SD37) |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The LOGON command allocates a CA Verify for CICS virtual terminal, anchors the terminal to the port being accessed by the exec when the LOGON command is executed, and uses the terminal to start a session with a named online system.
Examples:
" LOGON cics1 model mod2 "" LOGON &system data &uid "
Format:
LOGON system-name (MODEL terminal-model | MOD2 | MOD3 | MOD4 | MOD5 ) ( default-screen-size24X80 | 32X80 | 43X80 | 27X132 ) ( alternate-screen-size24X80 | 32X80 | 43X80 | 27X132 )| ( terminal-type
BASICDS | EXTDS )
(FROM terminal-name )
(DATA logon-data )
( buffer-format
BASICDATA | EXTDSDATA | PANELDATA | IMAGEDATA | ATTRIBUTES attr-values )( USERMOD ispf-usermod )
The 1 through 8 character name of an online system with which a session is to be started. The system name specified may be an actual name, a literal value or a REXX variable, coded with a leading ampersand, that contains the name of an online system.
An optional keyword and indicates that the value that follows is a symbolic terminal model name or the name of a mode table entry.
The logon mode table entry to be used to start a session. It may be one of the keywords MOD2, MOD3, MOD4 or MOD5, to refer to a mode table entry name, or it may be the actual name of a logon mode table entry. terminal-model may be expressed as an actual value, or may be a variable field that contains a valid terminal model value or null value.
(Optional) Indicates the default virtual terminal screen size to be used for a session. default-screen-size may be one of the keywords 24X80, 32X80, 43X80, or 27X132, expressed as an actual value, or as a variable field that contains a screen size keyword or a null value.
(Optional) Indicates the alternate virtual terminal screen size to be used for a session. alternate-screen-size may be one of the keywords 24X80, 32X80, 43X80, or 27X132, expressed as an actual value, or as a variable field that contains a screen size keyword or a null value.
(Optional) Specifies the type of terminal to be used for a session. terminal-type may be one of the keywords BASICDS or EXTDS, expressed as an actual value, or as a variable field that contains a terminal type keyword or null value.
An optional keyword that indicates that the data item that follows is a virtual terminal name.
The name of the virtual terminal to be used for the session. terminal-name may be the actual name of a VTAM APPL that has been defined at an installation for use as a CA Verify for CICS virtual terminal or may be a variable field that contains a virtual terminal name or a null value. If the FROM keyword is not specified or if terminal-name is a variable field that contains a null value, then a virtual terminal will be assigned automatically.
An optional keyword that indicates that the data item that follows is logon data.
A data item identified by the DATA keyword that is to be sent to an online system with a session request. logon-data may be a variable field that contains logon data and may be up to 255 characters in length, or may be one or more consecutive literal values whose accumulated length(s) do not exceed 255 characters. When the DATA keyword is not specified or if logon-data is a variable field that contains no data, then data is not included in the session request sent to an online system.
An optional keyword that specifies the format of the virtual terminal display buffer data returned in REXX variables PTEBUFF and PTEEAB at the completion of the LOGON command and subsequent session commands. Refer to 3270 Attribute Values for the values and meanings of basic, panel and extds attributes and extended attribute data.
An optional keyword that indicates that the value that follows is an ISPF usermod value.
Immediately follows the USERMOD keyword and specifies a one-byte value, expressed as a single character or as a two-character hexadecimal value enclosed in single or double quotes. The ISPF-usermod value tells CA Verify for CICS the USERMOD value specified by an ISPF panel that is used to display an image of a virtual terminal screen. ISPF-usermod defaults to hexadecimal 3F.
The system name specified may be the actual VTAM APPL name by which an online system is known to VTAM or may be a familiar system id defined in CA Verify for CICS system options, that refers to an actual VTAM APPL.
If a null terminal model is specified in a CA Verify for CICS LOGON command, or if the MODEL keyword is not specified, then a default mode table entry name specified during CA Verify for CICS installation is used. The following table lists terminal model keywords and their associated default and alternate virtual terminal screen sizes.
|
Model Keyword |
Default Size |
Alternate size |
|---|---|---|
|
MOD2 |
24 X 80 |
24 X 80 |
|
MOD3 |
24 X 80 |
32 X 80 |
|
MOD4 |
24 X 80 |
43 x 80 |
|
MOD5 |
24 X 80 |
27 x 132 |
The first screen size keyword encountered in a LOGON command specifies the default screen size. If a default screen size is specified, it is used only when a session is started using a mode table entry that does not contain screen sizes, and sizes are not forced by an online system.
The second screen size keyword encountered in a LOGON command specifies the alternate screen size. If an alternate screen size is specified, it is used only when a session is started using a mode table entry that does not contain screen sizes, and sizes are not forced by an online system.
If screen sizes are not specified and are not defined in the mode table used to start a session and are not forced by an online system, then default sizes specified at an installation are used.
A terminal may be either a basic or extended 3270 data stream terminal. A basic data stream terminal has a single screen buffer that is used to store screen data and coded basic field attributes. An extended data stream terminal has a screen buffer that is used to store screen data and actual basic field attributes and has an extended attribute buffer that is used to store extended data stream color and highlighting attributes and other information.
If a terminal type is not specified, a default type specified at an installation is used. If an online system sends a 3270 Read Partition Query structured field to a terminal to determine device capabilities, the terminal type or screen sizes specified influence the contents of the reply.
After using the LOGON command to start a session, the CA Verify for CICS TYPE, INVITE, and DELAY commands are used to key data into the virtual terminal used for a session, to send input to the online system, to receive online system responses to input, and to receive messages initiated by an online system.
ISPF Session Panels explains how to use the LOGON command PANELDATA and USERMOD options to display an image of a virtual terminal screen using an ISPF panel, and how to key data entered by the user into a virtual terminal using the TYPE command USERMOD option.
At the completion of each CA Verify for CICS session command, session information is returned to the issuing exec in REXX variables. Refer to CA Verify for CICS REXX Variables for a description of each session variable.
A session is ended by an online system when a logoff transaction is entered using a TYPE command, or may be ended using a LOGOFF command. Sessions are terminated automatically if all execs in an address space end and leave sessions active.
At the completion of a LOGON command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes LOGON command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
LOGOFF |
16 |
|
Session ended |
|
ENDTRACE |
20 |
HALT |
Trace abended (ie., SD37) |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The MONITOR command instructs CA Verify for CICS to monitor or to stop monitoring specified events and specifies what to do when monitored events are detected. Detected events may be displayed at a terminal, written as REXX SAY messages, or may passed to a user-written exec that may process the event as desired. MONITOR command instructions apply to subsequent CA Verify for CICS commands issued by any exec that runs in the REXX Language Processor Environment in which the MONITOR command is issued, including execs that call or that are called by an exec that issues a MONITOR command. A MONITOR command may instruct CA Verify for CICS to monitor or to stop monitoring:
Examples:
" MONITOR SIGNALS "
" MONITOR SIGNALS CONDITIONS COMMANDS RESPONSES STORE DROP FETCH "
" MONITOR &REXXSYM &PTEMESS "
" MONITOR SIGNALS CONDITIONS COMMANDS RESPONSES VIAEXEC MONEXEC "
" MONITOR OFF "
Format:
MONITOR ( events )( &generic_symbols )( OFF )( VIASAY | VIATPUT | VIAEXEC monitor_exec )( NOTE ¬e | RECALL ¬e )
An optional list of keywords that name events to be monitored. When OFF is also specified monitoring is stopped for the specified events. Event keywords are:
Monitors operations performed by CA Verify for CICS commands on REXX variables whose names begin with any specified generic_symbol, or stops monitoring when OFF is also specified. For example, MONITOR &PTE &Q_VALUE, monitors CA Verify for CICS operations on variables whose names begin with PTEor Q_VALUE. When STORE, FETCH and/or DROP are also specified, only the specified operations are detected, otherwise all operations on variables whose names begin with specified &generic_symbols are detected.
Stops monitoring for specified events and/or &generic_symbols. If OFF is the only MONITORcommand option specified, then all monitoring is stopped.
Causes messages to be sent to the REXX SAY destination when monitored events other than RESPONSES are detected.
Causes messages to be sent to the TSO terminal using TSO TPUT, when monitored events other than RESPONSES are detected. In a non-TSO address space, VIATPUT sends messages to the REXX SAY destination.
Specifies that a named exec, monitor_exec, is to be called when a monitored event is detected. The Monitor Exec Interface documents arguments passed to a monitor_exec when it is called to process events and provides other information about monitor execs.
Saves the value of REXX variable note for subsequent recall by any exec that runs on the same port as the exec that saved the ¬e.
Returns a monitor note in REXX variable note that was saved by a MONITOR NOTE command issued by any exec running on the same port as the exec that recalls the ¬e.
By default, CA Verify for CICS commands are not monitored. While return codes, REXX conditions and information returned in REXX variables informs an exec about errors or other CA Verify for CICS conditions encountered by CA Verify for CICS commands, no information about CA Verify for CICS conditions is automatically displayed or otherwise made available to the user of an exec.
Because MONITOR commands apply to all execs that run in a REXX environment, general purpose execs that activate monitoring and call other execs may be used to debug execs without modification to the exec being debugged. In addition to debugging applications, the MONITOR command, monitor execs, other CA Verify for CICS commands, and ISPF commands may be used to monitor multi-session stress tests. More information about and examples of MONITOR command applications may be found in Monitoring Execs and Sessions.
At the completion of a MONITOR command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes MONITOR command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
A monitor exec specified using the MONITOR command VIAEXEC option is called to process all monitored events when they are detected. A default monitor exec is called to process online system responses when RESPONSES are monitored, but a monitor exec has not been specified using the MONITOR command VIAEXEC option. When a monitor exec is called to process an event, information about the event is passed to the monitor exec as CALL arguments. A monitor exec may assign the argument values to REXX variables using a REXX ARG instruction that has commas coded between specified variable names. The CALL arguments passed to a monitor exec are:
Prior to calling a monitor exec, active monitoring is turned off, and monitoring is restored when a monitor exec returns. A monitor exec may issue an ACCESS LASTPORT command to determine the port being accessed by the exec when the monitored event was detected, may issue a QUERY SESSION command to fetch a copy of all CA Verify for CICS defined session variables, or may issue any other CA Verify for CICS command including the MONITOR command. Monitor execs may also ADDRESS other command processors and use other commands that are valid in the REXX Language Processor Environment.
MONITOR NOTE and MONITOR RECALL functions are intended for use by monitor execs and other execs that control monitor functions and monitor execs. An exec that issues a MONITOR command that specifies a user-written monitor exec may pass information to the monitor exec using a monitor note. A monitor exec may recall information noted by another exec or may recall, update and note session statistics or other information needed when the monitor exec is called to process subsequent events. While there are no restrictions regarding the use of the MONITOR NOTE or RECALL functions, it is recommended that the functions be used only by monitor execs or execs that communicate or cooperate with monitor execs, to avoid conflicting use of notes if monitor execs are used to monitor other execs.
If a MONITOR command specifies RESPONSES, but does not specify VIAEXEC, a default monitor exec specified in CA Verify for CICS system options is called when subsequent online system responses or other outbound session events are processed by CA Verify for CICS session commands.
A distributed monitor exec, VTEMONX, is designed to be used as a default monitor exec. When called to process detected RESPONSE events, VTEMONX displays CA Verify for CICS session commands and virtual terminal screen images using ISPF display and pop-up services, when called in an ISPF REXX Language Processor Environment, or using the REXX SAY instruction, when called in a TSO or other REXX Language Processor Environment.
VTEMONX is distributed in the CA Verify for CICS CATJEXEC library. ISPF panels used by VTEMONX, VTEPXMDT and VTEPXMW2, are distributed in the CA Verify for CICS CATJPENU library.
VTEMONX should not be specified as a MONITOR command VIAEXEC. If called to process an event other than a RESPONSE event, VTEMONX ignores the event and returns. Monitored events other than RESPONSE events are displayed automatically if a VIAEXEC is not specified. However, a user-written monitor exec that processes other events may call VTEMONX to process RESPONSE events provided that it passes all arguments passed to it by CA Verify for CICS.
The POST command replaces the entire queue anchored to the port being accessed by an exec, with a single queue entry that contains specified argument values. If a PULL command issued by an exec running on another port is waiting for data to be stored in the queue, then the oldest waiting PULL command is resumed when the queue entry is posted.
Examples:
" POST 'saymsg' &PTEMESS " " POST &item1 &item2 &item3 "
Format:
POST (arg1 . . . arg20)
(Optional) Argument which specifies up to 20 values, either literal values contained in single or double quotes, or REXX variables, coded with a leading ampersand, that contain argument values to be stored in the posted queue entry. A null queue entry is posted if no arguments are specified.
If the POST command is used to post updated information and QUERY QUEUE commands are used to examine the information, a queue becomes a bulletin board that may be used to provide current information to any number of other execs. QUEUE and PULL commands may be used to process queue entries in the order that they were queued. PUSH and PULL commands may be used to process the most recently queued entry first.
At the completion of a POST command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The PULL command assigns argument values fetched from the top entry of the queue anchored to the port being accessed by an exec when the command is issued, to variables specified by the PULL command.
Example:
" PULL &var1 &var2 &var3 "
Format:
PULL (&variable1 . . . &variable20)
The names of up to 20 variables, coded with a leading ampersand, to which pulled argument values may be assigned.
Argument values stored in the pulled queue entry by a QUEUE, PUSH, or POST command are returned in the corresponding variables specified by a PULL command.
If the number of variables specified exceeds the number of argument values in the pulled queue entry, then a zero-length value is assigned to excess variables. If the number of argument values in a pulled queue entry exceeds the number of variables specified by the PULL command, then excess argument values are discarded.
A CA Verify for CICS WAIT command that specifies ON PULL may be issued to specify a time interval that subsequent PULL commands are to wait for data to be queued in the event that an accessed queue is empty when a PULL command is issued. A PULL completes normally if queued data is immediately available or if data is queued within a specified time interval. If an accessed queue is empty and a WAIT interval was not specified or a specified interval expires before data is queued, the PULL command completes with return code 12 to indicate the CA Verify for CICS ENDQUEUE condition.
At the completion of a PULL command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes PULL command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
ENDQUEUE |
12 |
|
Data queue was empty |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The PUSH command adds an entry to the top of the queue anchored to the port being accessed by an exec when the command is issued, that contains specified argument values. If a PULL command issued by an exec running on another port, is waiting for data to be stored in the queue, then the oldest waiting PULL command is resumed when an entry is queued by a PUSH command.
Examples:
" PUSH 'INQUIRE' &ACCOUNT "
" PUSH &item1 &item2 &item3 "
Format:
PUSH (arg1 . . . arg20)
(Optional) Argument which specifies up to 20 values, either literal values contained in single or double quotes, or REXX variables, coded with a leading ampersand, that contain argument values to be stored in the queue entry. A null entry is queued if no arguments are specified.
When the PUSH command is used to queue data and the PULL command is used to process it, the most recently queued entries are processed first. QUEUE and PULL commands may be used to process queue entries in the order that they were queued. A queue may also be used as a bulletin board to post current information that may be examined to any number of other execs using the POST and QUERY QUEUE commands.
At the completion of a PUSH command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes PUSH command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The QUERY command returns requested information about CA Verify for CICS resources in REXX variables. The QUERY command may be used to:
Examples:
" QUERY session "
" QUERY sessions "
" QUERY queue &var1 &var2 &var3 "
Format:
QUERY
( QUEUE (&variable1 . . . &variable20) | QUEUES | SESSION ( LOGONDATA |
BASICDATA | EXTDSDATA |
PANELDATA | IMAGEDATA ) | SESSIONS | TASK | TASKS |
TRACE | TRACES )
Keywords that identify the CA Verify for CICS resource or resources about which information is to be returned.
Can be specified when a QUEUE is queried, they are the names of up to 20 REXX variables, coded with a leading ampersand, to which the queried argument values are to be assigned.
Keywords that may be specified when a SESSION is queried to specify the format of the virtual terminal display buffers returned in variables PTEBUFF and PTEEAB.
When QUEUES, SESSIONS, TASKS or TRACES is specified, NOQUEUES, NOSESSIONS, NOTASKS or NOTRACES is returned in variable, PTEINFO, if the queried resource does not exist on any CA Verify for CICS port. Otherwise QUEUES, SESSIONS, TASKS, or TRACES is returned in PTEINFO and a list of the ports on which the queried resource exists is returned in PTEPORTS. For example:
When QUEUE, SESSION, TASK or TRACE is specified, NOQUEUE, NOSESSION, NOTASK or NOTRACE is returned in PTEINFO, if the queried resource is not active on the port being accessed by the exec when the QUERY command is issued. Otherwise QUEUE, SESSION, TASK or TRACE is returned in PTEINFO.
When a QUERY QUEUE command specifies one or more variables, &variable1 through &variable20, and the accessed queue contains data, then values obtained from the top entry in the queue are returned in corresponding variables specified by the QUERY command. If the number of variables specified exceeds the number of values in the top queue entry, a zero-length value is returned in excess variables. The QUERY QUEUE command works like the PULL command, except that the QUERY command does not remove data from a queue.
A QUERY SESSION command returns the same information in session variables that is returned by all CA Verify for CICS session commands, and drops session variables if a session is not active on the accessed port. However, a QUERY SESSION command may specify one of the keywords, LOGONDATA, BASICDATA, EXTDSDATA, PANELDATA or IMAGEDATA, to override the format of the virtual terminal display buffers returned by the QUERY command in PTEBUFF and PTEEAB. By default or when LOGONDATA is specified, buffer data is returned using the format specified by the LOGON command that started the queried session. Refer to LOGON for a description of the format of the buffer data returned when other optional format keywords are specified. Refer to CA Verify for CICS REXX Variables for a description of all session variables.
At the completion of a QUERY command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes QUERY command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The QUEUE command adds an entry to the bottom of the queue anchored to the port being accessed by an exec when the command is issued, that contains specified argument values. If a PULL command issued by an exec running on another port is waiting for data to be stored in the queue, then the oldest waiting PULL command is resumed when the queue entry is added.
Examples:
" QUEUE 'INQUIRE' &ACCOUNT "
" QUEUE &item1 &item2 &item3 "
Format:
QUEUE (arg1 . . . arg20)
(Optional) Arguments which specify up to 20 values, either literal values contained in single or double quotes or REXX variables, coded with a leading ampersand, that contain argument values to be stored in the queue entry. A null entry is queued if no arguments are specified.
When the QUEUE command is used to queue data and the PULL command is used to process it, queue entries are processed in the order they were queued. PUSH and PULL commands may be used to to process the most recently queued entry first. A queue may also be used as a bulletin board to post current information that may be examined to any number of other execs using the POST and QUERY QUEUE commands.
At the completion of a QUEUE command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes QUEUE command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The SIGNAL command instructs subsequent CA Verify for CICS commands to signal the occurrence of a specified CA Verify for CICS condition by raising a REXX ERROR, FAILURE or HALT condition, or to raise no REXX condition if a specified CA Verify for CICS condition is encountered.
Examples:
" SIGNAL OFF ON ENDTRACE "
" SIGNAL ERROR ON LOGOFF "
Format:
SIGNAL REXX-cond ON Verify-cond
REXX-cond is one of the keywords, ERROR, FAILURE, HALT or OFF.
ON is required and identifies the Verify-cond that follows.
Verify-cond is one of the CA Verify for CICS condition keywords, LOCKOUT, TIMEOUT, ENDQUEUE, LOGOFF, ENDTRACE, CANCEL or FAULT.
All unusual events and errors that can be detected by CA Verify for CICS commands are categorized into named groups called Verify conditions. Each Verify condition is associated with a unique return code that is returned in the REXX RC variable when a Verify condition is detected. The following table is a summary of all possible Verify condition and return codes and default REXX conditions raised for some CA Verify for CICS conditions.
The CA Verify for CICS SIGNAL command is designed for use with REXX SIGNAL and CALL instructions to trap CA Verify for CICS conditions using REXX condition traps, or may be used to avoid REXX conditions that are raised by default for some CA Verify for CICS conditions.
For example, instead of checking the return code following each CA Verify for CICS session command to detect and process an unexpected session failure, a CA Verify for CICS SIGNAL command and a REXX SIGNAL instruction may be used to detect and process an unexpected session failure.
If a session is traced, but a trace failure is not a big enough problem to interrupt an exec, the SIGNAL command may be used to override the REXX HALT condition that is raised by default when a CA Verify for CICS ENDTRACE condition occurs.
" SIGNAL OFF ON ENDTRACE " " trace to tracedd " " SIGNAL ERROR ON LOGOFF " signal ON ERROR name ended " logon cics " say 'session ended:' PTEMESS
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
TIMEOUT |
8 |
|
Timed out waiting for response |
|
ENDQUEUE |
12 |
|
Data queue was empty |
|
LOGOFF |
16 |
|
Session ended |
|
ENDTRACE |
20 |
HALT |
Trace abended |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
At the completion of a SIGNAL command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table defines the CA Verify for CICS conditions, return codes and default REXX conditions that may be raised by the SIGNAL command.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The TRACE command starts a CA Verify for CICS session trace on the port being accessed by an exec when the command is issued. While a session trace is active, CA Verify for CICS writes the current image of a virtual terminal screen image to a trace data set whenever a TYPE command sends data to an online system and when an online system sends a response or other message to the virtual terminal being used for a session.
Examples:
" TRACE to tracedd image freekb "
" TRACE 'change caption to this' "
" TRACE to &ddname format pack "
Format:
TRACE TO ddname ( FORMAT | IMAGE | UPPERCASE ) ( DELAYS | DELAYSOFF ) ( LOGONS | LOGONSOFF ) ( CHAINS | FREEKB ) ( PACK | NOPACK )| ( caption )
Specifies the DD name to be opened to capture screen images when CA Verify for CICS session commands are used to send and receive data using the session anchored to the same port as the session trace.
(Optional) Keyword which specifies that traced screen images are to contain all screen data.
(Optional) Keyword which specifies that traced screen images are to be edited, to convert attributes and other non-display data to blanks and graphic escape characters to dashes, producing screen images similar to screen images visible to users of the system.
(Optional) Keyword which specifies that traced screen images are to be edited and converted to all upper case characters.
Specifies that user think time is to be captured as DELAY statements in the trace data set. DELAYSOFF specifies that no DELAY statements are to be created.
Specifies that LOGON statements are to be captured when a session is started. LOGONSOFF specifies that no LOGON statements are to be created.
Specifies that all outbound screen images are to be traced. FREEKB specifies that outbound screens images are to be captured only when an outbound message frees the terminal keyboard.
Specifies that traced session data is to be written using the ISPF packed data format. NOPACK specifies that traced screen images are to be written as unpacked, fixed-length records.
a literal value that is to be used as the caption of subsequently traced screen images, and may be specified when a trace is started or at any time while a trace is active. A caption must be enclosed in either single or double quotes.
Default values for all optional parameters are controlled by CA Verify for CICS system options.
The TRACE command starts or modifies the trace on the port that is being accessed TRACE command is issued.
A trace may be started or ended before, during and after a session is started or ended to capture any portion of a session.
A trace is ended using the ENDTRACE command or is ended automatically when all execs in an address space have ended.
At the completion of a TRACE command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes TRACE command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
ENDTRACE |
20 |
HALT |
Trace abended (ie., SD37) |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The TYPE command operates a virtual terminal by pressing keys on a virtual terminal keyboard that perform the same functions as the keys on a real terminal keyboard. For example, a tab key moves the cursor to the next modifiable field. When a data key is pressed, each character of the data is keyed in at the current cursor position, the modified data tag is turned on in the attribute that controls the field, and the cursor advances one position or skips to the next field if the position is a skip attribute.
A TYPE command uses the keyboard of the virtual terminal that is anchored to the CA Verify for CICS port being accessed by an exec when a TYPE command is issued, to position the cursor, to type literal, variable and other data values, to erase fields, to send data to an online system, and to perform other keyboard operations specified by the command. The keyboard operations specified by a TYPE command are performed in the order in which they are coded.
Examples:
" TYPE home erase 'cemt set' "," ' da(&dd) open ena' enter "
" TYPE clear "
" TYPE <2 15> 'inq' "
" TYPE <4 15> 'smith' enter "
" TYPE <&row &col> &data1 "" TYPE <4 15> &data2 enter "
" TYPE home tab &account "," tab &order pf2 "
" TYPE usermod <&cursor> "pfkey
Format:
TYPE ( <row column> )
( <position> )
( HOME TAB BACKTAB NEWLINE )
( 'literal-data' )
( "literal-data" )
( &variable-data )
( ERASE )
( SELECT | DESELECT )
( TOKEN token )
( CODE code )
( USERMOD )
( ENTER | PF1-24 | PA1-3 |
PEN | CLEAR | ATTN |AID &aid-variable )
TYPE
Moves the cursor to the specified virtual terminal screen row and column. A row or column may be a row or column number or the name of a REXX variable, coded with a leading ampersand, whose value is a row or column number.
Moves the cursor to the specified virtual terminal screen position, where position = (row - 1) * PTECOLS + column. position may be a number or the name of a REXX variable, coded with a leading ampersand, whose value is a screen position.
Move the cursor to the first modifiable screen field, to the field that follows or precedes the current cursor location, or to the first modifiable screen position that follows the current cursor row.
Types the indicated data, which must be enclosed in single or double quotes.
Types the data contained in a named REXX variable, coded with a leading ampersand.
Erases the remainder of the modifiable screen field, beginning at the current cursor position.
Keywords select or deselect the pen detectable selection or attention field at the current cursor location. The operations simulate operations performed by a 3270 light pen or cursor select key, with the following exceptions:
Identifies a CA Verify for CICS password token, which follows the TOKEN keyword. token may be a literal value or a REXX variable coded with a leading ampersand, that contains a token (for example, &token). A token represents a password that is encrypted as described in Token Security. A token:
Identifies a CA Verify for CICS password code, which follows the CODE keyword. code may be a literal value or a REXX variable, coded with a leading ampersand, that contains a code (for example, &code). A code is a password or other data that is encoded as described in Code Security. A code:
Fetches data from fields of the virtual terminal display buffer in REXX variable, PTEBUFF, whose attribute values match a USERMOD value specified by the LOGON command that started a session, and rekeys the data into corresponding fields of the session's virtual terminal display buffer.
Keywords send data to an online system that is formatted like the data sent when a like-named key is pressed on a real terminal keyboard. The AID keyword identifies a variable that follows, &aid, which contains the name of the key to be pressed to send data. Virtual terminal keys that send data may be coded as the last TYPE command keystroke only.
A TYPE command that does not specify a key that sends data to an online system completes when the last specified keyboard operation has been performed.
When a key that sends data is pressed, the virtual terminal keyboard is locked and data identical to the data sent by a real terminal is sent to the online system. After sending data, the TYPE command normally waits for and receives response messages from the online system, until a message is received that frees the terminal keyboard, before returning to the exec that issued the command.
The HANDLE command may be issued to instruct the TYPE command to return immediately after sending data or to return after receiving any message even if the message does not free the keyboard. A TYPE command completes with a TIMEOUT condition if a response is not received within a time limit specified by a previous WAIT command.
The TYPE command returns updated information in session variables, as documented in CA Verify for CICS REXX Variables.
At the completion of a TYPE command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes TYPE command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Times out waiting for port lock |
|
TIMEOUT |
8 |
|
Timed out waiting for response |
|
LOGOFF |
16 |
|
Session ended |
|
ENDTRACE |
20 |
HALT |
Trace abended (ie., SD37) |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
34 |
HALT |
Invalid command or system error |
The UNLOCK command unlocks the port being accessed by an exec when the command is issued. A port may be unlocked only by an exec that is running on the same port as the exec that issued the LOCK or ACCESS command that locked the port.
If another exec task was delayed because it attempted to use resources anchored to the port being unlocked, the exec task is resumed when the port is unlocked.
Example:
" UNLOCK "
Format:
UNLOCK
At the completion of an UNLOCK command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes UNLOCK command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
LOCKOUT |
4 |
|
Timed out waiting for port lock |
|
TIMEOUT |
8 |
|
Time out waiting for response |
|
LOGOFF |
16 |
|
Session ended |
|
ENDTRACE |
20 |
HALT |
Trace abended |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
The WAIT command waits for a specified period of time to elapse, or limits the amount of time that subsequent CA Verify for CICS commands wait for online system responses, data to be queued, or locks.
Examples:
" WAIT &mssth "
" WAIT 50000 on response "
" WAIT forever on pull "
Format:
WAIT hhmmssth | FOREVER
( ON event )
Descriptions
hhmmssth is a time interval, expressed in hours (hh), minutes (mm), seconds (ss) and tenths and hundredths of seconds (th), or the keyword, FOREVER. FOREVER is valid only when ON event is specified.
ON event is optional. If not specified, the WAIT command simply waits for the specified interval to elapse. ON indicates that the time limit applies only when waiting for a named event to complete.
At the completion of a WAIT command, the REXX variable RC indicates any CA Verify for CICS condition encountered while executing the command. The following table describes WAIT command return codes and default REXX conditions that may be raised for some CA Verify for CICS conditions.
|
Conditions |
RC |
Default Signal |
Reason for Condition |
|---|---|---|---|
|
|
0 |
|
Command completed successfully |
|
CANCEL |
24 |
HALT |
CANCEL command processed |
|
FAULT |
64 |
HALT |
Invalid command or system error |
|
Copyright © 2012 CA.
All rights reserved.
|
|