Previous Topic: VSE JCLNext Topic: REXX Reference


Commands for REXX

This chapter describes the CA Verify for CICS Host Command Environment which allows REXX execs to ADDRESS VERIFY and use virtual terminals in a multi-session synchronous or asynchronous environment.

The CA Verify for CICS Host Command Environment allows REXX execs to ADDRESS VERIFY and to issue CA Verify for CICS host commands.

This section contains the following topics:

The Session Commands

Tracing Exec-Driven Sessions

Ports and Multiple Sessions

Sharing Sessions with Called Execs

Attaching Asynchronous Exec Tasks

Queues and Intertask Communication

Sharing Resources with Attached Execs

Smart Exec-Driven Sessions

ISPF Session Panels

Monitoring Execs and Sessions

The Session Commands

CA Verify for CICS session commands may be used by REXX execs to start sessions with online systems using virtual terminals and to use virtual terminals in the same way that people use real terminals to access online system software.

CA Verify for CICS session commands return information to execs in REXX variables. At the completion of each session command, a copy of the virtual terminal display buffer is returned in a REXX variable, PTEBUFF, the virtual terminal screen size and cursor position are stored in PTEROWS, PTECOLS and PTECSRP, and other information about the virtual terminal and session is returned in other REXX variables. Using the returned display buffer, execs may analyze transaction responses and gather displayed information or use it to enter subsequent transactions.

REXX execs that repeat captured sessions may be created automatically by converting previously logged test streams to execs. When a logged test stream is converted to REXX, session initiation is captured as a LOGON command and user keystrokes are captured as TYPE commands. Converted execs also include INVITE commands that wait for anticipated system messages and may include DELAY commands that capture actual human think-time delays that occur while logging a test stream. A converted exec may be executed to repeat a captured session automatically.

By modifying a captured exec or by writing execs from scratch, intelligent REXX execs may be developed that use the application's sessions and any available online system software to reliably perform or automate almost any imaginable terminal task that could by performed by a person using a terminal.

The REXX exec in the following example uses the application session commands to start a session and to use transactions designed for users.

     /* Exec: OPEN CA Verify commands for REXX: */      /* LOGON INVITE TYPE LOGOFF */ (1)      address Verify (2)   "  logon cics 24x80 24x80 basicds "       "  invite 1000 "       "  type clear " (3)   "  type 'cemt set dataset(somedd) open' enter " (4)      if substr(PTEBUFF,224,6) = 'NORMAL' then             say 'open worked ok'          else             say 'open failed!!!'       "  type pf3 " (5)   "  logoff "

Tracing Exec-Driven Sessions

CA Verify for CICS TRACE and ENDTRACE commands can be used to capture an exec-driven CA Verify for CICS session. When a session is traced, a screen image is captured in a trace data set whenever a TYPE command sends data to an online system. Another screen is captured when a response or other message sent by an online system is received at the virtual terminal used for a session.

In the following example, an exec named TRACE uses TRACE and ENDTRACE commands to capture a CICS session.

      /* Exec: TRACE VERIFY commands for REXX:       */       /*       TRACE LOGON INVITE TYPE ENDTRACE       */ (1)      address TSO        " allocate f(tracedd) sysout(a) " (2)      address Verify        " TRACE to tracedd image " (3)    " LOGON cics1 model mod2 "        " INVITE 1000 "        " TYPE clear "        " TYPE 'cemt set dataset(somedd) open' ",        " enter "          if substr(PTEBUFF,224,6) = 'NORMAL' then             say 'open worked ok'          else             say 'open failed!!!'        " TYPE pf3 "        " TYPE home 'logoff' erase enter " (4)    " ENDTRACE " (5)      address TSO        " free f(tracedd) "

Ports and Multiple Sessions

A CA Verify for CICS port is a place to anchor the application session, session trace, data queue and/or a REXX environment. Each CA Verify for CICS port is identified by a number. When the first exec in an address space issues a command, the exec's REXX environment is anchored to port 1.

CA Verify for CICS commands that operate on sessions, traces, execs or queues, create or use the session, trace, REXX environment or queue anchored to the numbered port being accessed by the exec when the command is issued. By default, an exec accesses the port to which its REXX environment is anchored. If an exec issues a CA Verify for CICS LOGON command, causing the exec's REXX environment to be anchored to port 1, the LOGON command allocates and anchors a virtual terminal to port 1 and uses the terminal to start a session on port 1.

While only one session may be active on a particular port at any point in time, an exec may use the ACCESS command to access another port and may use the LOGON command to start a session on the accessed port.

For example, ACCESS 2 instructs subsequent commands to create or use port 2 resources. While accessing port 2, a LOGON command would allocate a virtual terminal and use it to start a session on port 2, and TYPE commands would use the port 2 virtual terminal keyboard to enter transactions. An exec may use the ACCESS command multiple times to start multiple sessions on different ports, and may access a specific port at any time to enter transactions using the session anchored to the accessed port.

In addition to instructing subsequent commands to create or use resources anchored to a particular port, each ACCESS command also instructs session commands to return session information to an exec using either simple or compound session variable names.

By default, or if an exec issues an ACCESS EXECPORT command to access the port its REXX environment is anchored to, session commands return session information to the exec using the defined simple session variable names.

If an exec issues an ACCESS NEWPORT command to access a previously unused port, or an ACCESS FREEPORT command to reuse a port that is no longer being used, or if an exec issues an ACCESS command that specifies a port number, including the number of the port that the exec's environment is anchored to, the ACCESS command instructs subsequent session commands to return session information to the exec using compound session variable names.

As a result, when an exec uses the ACCESS command to start and use multiple sessions on multiple ports, the exec may refer to returned session information using either simple variable names or using compound variable names that have an actual or variable port number as a tail, that refers to information about a particular session.

The REXX exec in the following example uses ACCESS commands to start three sessions on three ports, to run three long running end-of-day transactions concurrently. The exec also uses CA Verify for CICS HANDLE and WAIT commands to control session flow and timing.

     /* Exec: MULTISES CA Verify commands for REXX: */      /* ACCESS LOGON INVITE HANDLE WAIT */         address Verify (1)     sys.1 = 'cicsa'         sys.2 = 'cicsb'         sys.3 = 'cicsc'         do port=1 to 3       " ACCESS &port "       " LOGON &sys.port model mod2 "       " INVITE 1000 "       " TYPE clear "       " HANDLE turnaround off "       " TYPE 'long running end-of-day tran' ",       " enter "       " HANDLE turnaround on "         end (2)   " WAIT 10000 on response "         do until done = 3            done = 0            do port=1 to 3               if PTEKB.port = 'INHIBITED' then do       " ACCESS &port "       " INVITE "         end       else         done = done + 1       end     end

Sharing Sessions with Called Execs

When an exec calls another exec, the called exec runs in the same REXX environment as the calling exec, and by default accesses the port to which the REXX environment is anchored.

An exec may issue a LOGON command to start a session, then call another exec that issues a TYPE command to sign on. However, REXX variable pools are not shared by called and calling execs. When the called exec issues the TYPE command, PTEBUFF and other session variables are returned to the called exec, and PTEBUFF and other session information in the calling exec's variable pool becomes obsolete.

If an exec starts a session then calls another exec that uses the session, when the called exec returns, the calling exec may refresh session variables in its REXX variable pool using the QUERY SESSION command.

In the following example LOGON issues a LOGON command, then calls SIGNON to sign on. When SIGNON returns, LOGON uses the QUERY SESSION command to determine the status of the session and to refresh PTEBUFF and other session information.

     /* Exec: LOGON Verify commands for REXX: */      /* LOGON QUERY TYPE */         address Verify       " LOGON cics1 model mod2 "         call 'SIGNON'       " QUERY session "         select            when PTEINFO = 'NOSESSION' then do               say 'session failed'               exit               end            when substr(PTEBUFF,2,15),               \= 'Signon Complete' then do               say 'sign on failed'               exit               end            otherwise       " TYPE clear "            end      /* etc. */      /* Exec: SIGNON Verify commands for REXX: */      /* INVITE TYPE */         address Verify       " INVITE 1000 "       " TYPE 'uid1' token 'uid1a' enter "          return

CA Verify for CICS resources are cleaned up automatically when the first exec that runs in the port 1 REXX environment ends. If an exec called another exec to start a session before it issued a CA Verify for CICS command, the REXX environment would be anchored to port 1 when the called exec issued the LOGON command, and would be the first exec in the port 1 REXX environment. The session would be cleaned up automatically by CA Verify for CICS when the called exec returned to the calling exec.

If no active exec in an address space is using CA Verify for CICS commands, and an exec is executed that intends to use resources created by a called exec, it must issue some CA Verify for CICS command, for example, ACCESS EXECPORT, before calling an exec that creates the resources, to ensure that the resources are not cleaned up when the called exec ends.

Attaching Asynchronous Exec Tasks

When an exec creates multiple sessions on multiple ports, then uses the ACCESS command to switch from session to session, the events on the multiple sessions occur serially or synchronously. That is, only one TYPE command can be active at a time. Each TYPE command must complete before the exec can ACCESS another port or execute another TYPE command. The same is true if an exec calls another exec, because the called exec must return before the calling exec can execute additional session commands.

The CA Verify for CICS ATTACH command may be used to attach an exec that runs at the same time as the attaching exec. Unlike calling and called execs that run synchronously and in the same REXX Language Processor Environment, attaching and attached execs run asynchronously in different REXX Language Processor Environments and as separate z/OS tasks.

An ATTACH command specifies the name of the exec to be attached and may specify up to 20 literal or variable argument values to be passed to the attached exec. An ATTACH command may also specify REXX libraries to be used to load execs, the destination of REXX SAY messages issued by the attached exec and/or the destination of error messages issued by REXX while the exec is executing.

The ATTACH command creates a new z/OS task and a REXX Language Processor Environment that are used to run the attached exec. The REXX environment is anchored to the port being accessed by the attaching exec when the command is issued. Before issuing an ATTACH command, an ACCESS command must be issued to access a CA Verify for CICS port that is not already associated with a REXX environment.

After loading the attached exec in the new REXX environment, the ATTACH command completes and the attaching exec resumes execution at the same time that the attached exec begins execution.

Attached execs run as peer-to-peer tasks and are not arranged in a hierarchy. No notification is given to an attaching task when an attached task ends. An attaching exec may end before an attached exec ends. Any exec in an address space may use the ATTACH command to attach any other exec and any attached exec may use any CA Verify for CICS command to create application resources or to use resources created by any other exec running on any port in the address space.

Sessions, traces, data queues and other CA Verify for CICS resources created by execs are cleaned up automatically by CA Verify for CICS only when the first exec running in the port 1 REXX environment end. When the port 1 exec ends, cleanup is delayed until any other active execs that have issued CA Verify for CICS commands have ended.

In the following example an exec named FAST, attaches another exec named CHANGE 10 times to change a user password in 10 remote systems. The result would be the same if FAST called CHANGE10 times instead of attaching it. However, because called execs run one at a time, and because attached execs run at the same time, the ATTACH solution runs 10 times faster.

     /* Exec: FAST Verify commands for REXX: */      /* ACCESS ATTACH */ (1)     arg uid oldpt newpt         address Verify         do n=1 to 10 (2)   " ACCESS newport "       " ATTACH exec change ",       " &uid &oldpt &newpt 'tso"n"' "             end      /* Exec: CHANGE Verify commands for REXX: */      /* MONITOR LOGON INVITE TYPE */ (3)     arg uid oldpt newpt tson         address Verify       " MONITOR signals " (4)   " LOGON &tson data &uid "         do until substr(PTEBUFF,34,11),            = 'TSO/E LOGON'       " INVITE 1000 "            end (5)   " TYPE token &oldpt tab token &newpt enter "         if substr(PTEBUFF,11,16)            ª= 'REENTER PASSWORD' then do       " TYPE token token &newpt enter "           if substr(PTEBUFF,11,16)           ª= 'PASSWORD CHANGED' then do               say tson 'password changed'           exit              end           end        say tson 'password change failed'

Queues and Intertask Communication

Attached execs that run as asynchronous z/OS tasks may use CA Verify for CICS data queues to communicate. Like the commands that attach execs and manage sessions, CA Verify for CICS commands that manage data queues operate on the data queue anchored to the port being accessed by an exec when a command is executed.

QUEUE, PUSH, and POST Commands

QUEUE, PUSH and POST commands may store up to 20 literal or variable argument values as a single entry in an accessed queue. PULL and QUERY QUEUE commands return the argument values fetched from an accessed queue entry in corresponding REXX variables specified by the PULL or QUERY QUEUE command.

Data queues can be used in any desired way:

By default, if an accessed queue is empty when a PULL command is issued, RC=12is returned to the exec and the command completes immediately. An exec designed to process data queued by other execs may use the WAIT command to instruct subsequent PULL commands to wait a specified amount of time or to wait FOREVER for an entry to be queued, if the accessed queue is empty when a PULL command is issued.

The SERVER and SESSION execs in the following examples illustrate two uses of CA Verify for CICS data queues. The SERVER exec attaches SESSION execs to multiple ports and distributes a file of data to the queues anchored to SESSION exec ports. Each SESSION exec starts a session and uses the session to process queue entries pulled from the queue anchored to the SESSION exec's port. After processing each distributed queue entry, the SESSION exec returns a status message to the queue anchored to the SERVER exec's port. After logging a status message pulled from the SERVER exec's queue, the SERVER exec distributes another record to the SESSION exec that returned the logged status message.

Attached execs that drive asynchronous sessions and communicate using data queues may be used to perform system stress testing or may be used in production applications to multiply the throughput possible using conventional serial data processing methods.

     /* Exec: SERVER Verify commands for REXX: */      /* ACCESS QUEUE ATTACH WAIT PULL */ (1)     address TSO       " alloc f(quefile) da('appl.quedata') shr "       " alloc f(logfile) da('appl.logdata') mod "         querecs = 0 (2)     do 10 address TSO      " execio 1 diskr quefile      " if rc \= 0 then do querec = 'eof' leave end pull querec querecs = querecs + 1 address Verify      " ACCESS newport      "      " QUEUE &querec      "      " ATTACH exec session &pteport      " end address Verify      " WAIT forever on pull      " (3) do while querec \= 'eof'      " ACCESS execport      "      " PULL &logrec &port      " address TSO queue logrec      " execio 1 diskw logfile      " querecs = querecs - 1      " execio 1 diskr quefile      " if rc = 0 then do pull querec querecs = querecs + 1 end else querec = 'eof' address Verify      " ACCESS &port      "      " QUEUE &querec      " end (4) do while querecs > 0      " ACCESS EXECPORT      "      " PULL &logrec &port      " address TSO queue logrec      " execio 1 diskw logfile      " querecs = querecs - 1 address Verify           " ACCESS &port           "           " QUEUE 'eof'           " end (5) address TSO           " execio 0 diskr quefile (FINIS           "           " free f(quefile)           "           " execio 0 diskw logfile (FINIS           "           " free f(logfile)           

SERVER exec notes:

  1. The SERVER exec allocates a quefile that contains data to be processed, allocates a logfile used to collect status messages and initializes a count of in-progress quefile records to zero.
  2. The SERVER exec startup loop uses EXECIO and the REXX PULL instruction to read records sequentially from the quefile, and counts each record read as an in-progress quefile record. For each record read, the CA Verify for CICS ACCESS command is used to access an unused port, the QUEUE command is used to store the quefile record in the data queue anchored to the accessed port, and an ATTACH command is used to attach the SESSION exec to the accessed port to process quefile records distributed to the SESSION exec by the SERVER exec. An ATTACH parameter provides the SERVER exec’s port number to each attached SESSION exec.

    SESSION execs use the SERVER exec's port number to return status messages to the SERVER exec after processing each distributed quefile record. Before processing status messages, the SERVER exec uses the CA Verify for CICS WAIT command to instruct subsequent PULL commands to wait for a status message to be queued if the SERVER exec’s queue is empty when a PULL command is issued.

  3. Each iteration of the SERVER exec mainline loop logs a status message received from any attached SESSION exec and supplies another quefile record to the SESSION exec. The SERVER exec uses the ACCESS command to access the SERVER exec's port and uses the CA Verify for CICS PULL command to wait for and pull an entry from the SERVER exec’s queue. Each queue entry added to the SERVER exec's queue by an attached SESSION exec contains a status message and also the port number of the SESSION exec that added the entry to the SERVER exec’s queue. The REXX QUEUE instruction and EXECIO are used to write each pulled status message to the logfile managed by the SERVER exec, and the count of in-progress quefile records is decremented after logging the status message for a processed quefile record.

    After logging a status message returned by a SESSION exec, the SERVER uses EXECIO and the REXX PULL instruction to read another quefile record to be processed by the SESSION exec, and counts each record read as an in-progress quefile record. When the end of the quefile is reached, an 'eof' record is created to inform the SESSION exec that all quefile records have been processed and to signal the end of the SERVER mainline loop. The SERVER exec uses the port number that was pulled with the previous status message to ACCESS the SESSION exec's port and uses the QUEUE command to store either the next quefile record or the eof record in the SESSION exec's queue.

  4. When the end of the quefile has been reached, the SERVER exec pulls, logs and accounts for the status message for each in-progress quefile record, and queues an eof record to each SESSION exec that returns a final status message, until the count of in-progress quefile records is zero.
  5. After all quefile records have been processed and all status messages have been logged, quefile and logfile are closed and freed, and the SERVER exec ends.

/* Exec: SESSION Verify commands for REXX: */ /* LOGON INVITE TYPE LOGOFF */ /* WAIT ACCESS PULL QUEUE */ (1) arg logport address Verify " LOGON 'cics1' mod2 " " INVITE 1000 " " TYPE 'uid' token 'uida' enter " " TYPE clear " " TYPE 'tran' enter " " WAIT forever on pull " (2) do forever " ACCESS execport " " PULL &querec " if querec = 'eof' then leave " TYPE &querec enter " logrec = substr(PTEBUFF,23*80+1,80) " ACCESS &logport " " QUEUE &logrec &pteport " end (3) " TYPE clear " " LOGOFF

SESSION exec notes:

  1. Each attached copy of the SESSION exec uses the REXX ARG instruction to get the SERVER exec port number passed to the SESSION exec as a parameter by the ATTACH command used by the SERVER exec to attach the SESSION exec.

    The SESSION exec starts a session, signs on, and enters a tran that could be any transaction that processes any data contained in any querec.

    The CA Verify for CICS WAIT command is used to instruct subsequent PULL commands to wait for a querec to be queued if the SESSION exec's queue is empty when a PULL command is issued.

  2. Each iteration of the SESSION exec mainline uses ACCESS and PULL commands to wait for and to pull a querec from the SESSION exec's queue, uses CA Verify for CICS session commands to enter the pulled querec, and uses ACCESS and QUEUE commands to store an entry in the SERVER exec’s queue. The queue entry includes a status message displayed by 'tran' on screen row 24, and also includes the port number of the SESSION exec that stored the queue entry.
  3. An eofquerec instructs the SESSION exec to clean up its session and end.

Sharing Resources with Attached Execs

Attached execs run as z/OS tasks and may be executing at the same time using multiple hardware processors. When attached execs share CA Verify for CICS resources and multiple execs attempt to use a shared resource at exactly the same time, processor access to the shared resource is serialized automatically. For example, if two execs attempt to pull data from the same queue at the same time, the requests are processed serially and each exec pulls a different entry from the queue.

Locks are used to serialize access to resources. When an exec issues a CA Verify for CICS command that uses a shared resource, a lock is obtained that permits exclusive use of the resource by the exec task that owns the lock, before the resource is used. If an exec issues a command that uses a shared resource, while the resource lock is owned by another task, the task that wants the lock queues a lock requests and waits for the lock.

After a requested operation has been performed on a locked resource, if a lock request was queued by another exec task, ownership of the resource lock is transferred to the task that queued the oldest lock request and execution of the task that then owns the lock is resumed, otherwise the resource is unlocked.

Resource locks are obtained automatically by CA Verify for CICS commands when shared resources are used, but are held only for the life of the command. In some applications it may be necessary or convenient to hold resource locks while issuing a series of commands. An exec may use the CA Verify for CICS LOCK command or an ACCESS command that specifies the LOCK keyword to lock an accessed port. When a port is locked, the port and all resources anchored to the port are locked. A port lock is held until an UNLOCK command is issued.

If an exec issues commands that use resources anchored to a port that is locked by another exec task, or attempts to lock a port that is locked by another exec task, lock requests are queued and remain queued until the exec that holds the port lock unlocks the port.

An exec may lock a port to issue a series of commands that use resources anchored to the port, while preventing other execs from using port resources while the commands are executed. For example:

Smart Exec-Driven Sessions

REXX execs created by converting logged test streams contain CA Verify for CICS LOGON, TYPE, INVITE and DELAY commands that start sessions, re-key user keystrokes, and that handle other detected session events. When they are executed, converted REXX execs create sessions that are similar to the logged user session, provided that online system responses to re-keyed input are similar to online system responses to original input.

While converted REXX execs repeat only what a person did, and do not know why they did it or what they would have done if a system had responded to input in a different way, when a converted exec is executed, the virtual terminal screen images returned by session commands in REXX variables provides the same information to an exec that displayed online system responses provide to a terminal user.

REXX instructions and functions, returned session information and other CA Verify for CICS commands and command options may be used to develop intelligent REXX execs that make the decisions that people do. For example:

Intelligent REXX applications that use CA Verify for CICS session commands and any other resources available to REXX execs may be used to perform or automate almost any imaginable terminal task that could be performed by a person using a terminal.

ISPF Session Panels

Options of the CA Verify for CICS LOGON and TYPE commands make it easy to display CA Verify for CICS virtual terminal screen images using an ISPF panel and to rekey data entered at the displayed panel into the virtual terminal display.

The LOGON command PANELDATA keyword instructs subsequent CA Verify for CICS session commands to edit the virtual terminal display buffer returned in variable, PTEBUFF, for display using an ISPF panel similar to the panel shown in the following example.

)ATTR 01 TYPE(DATAIN)  INTENS(LOW)  SKIP(OFF) CAPS(OFF) JUST(ASIS) 05 TYPE(DATAIN)  INTENS(HIGH) SKIP(OFF) CAPS(OFF) JUST(ASIS) 07 TYPE(DATAIN)  INTENS(NON)  SKIP(OFF) CAPS(OFF) JUST(ASIS) 11 TYPE(DATAOUT) INTENS(LOW)  SKIP(OFF) CAPS(OFF) JUST(ASIS) 15 TYPE(DATAOUT) INTENS(HIGH) SKIP(OFF) CAPS(OFF) JUST(ASIS) 19 TYPE(DATAOUT) INTENS(LOW)  SKIP(ON)  CAPS(OFF) JUST(ASIS) 1D TYPE(DATAOUT) INTENS(HIGH) SKIP(ON)  CAPS(OFF) JUST(ASIS) | AREA(DYNAMIC)  EXTEND(ON)   USERMOD(3F) )BODY WIDTH(80) |PTEBUFF | )INIT .ALARM = &PTEALARM )PROC &CSRPOS = .CSRPOS &PFKEY = .PFKEY )END

  1. When a LOGON command specifies PANELDATA, basic 3270 attributes in the virtual terminal display buffer are returned in PTEBUFF as one of the seven attributes in the session panel definition. 3270 Attribute Values documents the mapping of basic 3270 attributes to panel attributes.
  2. PANELDATA also edits PTEBUFF data to remove nulls in protected fields that would otherwise be displayed as periods by ISPF.
  3. When the session panel is used to display a virtual terminal screen image, ISPF displays the PTEBUFF variable value returned by CA Verify for CICS session commands, in the PTEBUFF dynamic area defined in the body of the session panel.
  4. The USERMOD(3F) specification in the panel definition instructs ISPF to replace a field attribute in the PTEBUFF variable with the hexadecimal value, 3F, when data is keyed into a field. In a CA Verify for CICS LOGON command, USERMOD '3F' informs CA Verify for CICS of the USERMOD value defined in a session panel.
  5. CA Verify for CICS session commands return YES in variable, PTEALARM, when a message received from an online system sounds the terminal alarm. The reference to PTEALARM in the panel definition causes ISPF to echo an alarm at the terminal if an alarm was sounded at the virtual terminal.
  6. The PROC section of the panel definition instructs ISPF to return the cursor position and the PF key in variable fields CSRPOS and PFKEY, when data is entered and the ISPF DISPLAY command completes.

The exec named SESSMAN, shown in the following example is a TSO command that starts and manages an interactive session with a named online system. For example, 'TSO SESSMAN CICSA', may be entered while using any ISPF panel to start a session with an online system, CICSA. The SESSMAN exec uses a session panel, the ISPF DISPLAY command, and CA Verify for CICS session commands to start and display a virtual terminal session at a real terminal, rekey data entered at a terminal into the virtual terminal display, and send the data to an online system. To the user, a session managed by SESSMAN works much like any other terminal session.

    /* Exec: SESSMAN Verify commands for REXX: *    /     /* MONITOR SIGNAL LOGON DELAY TYPE *    / (1) arg system address Verify (2)      " monitor signals      "      " signal error on logoff      " (3)      " logon &system paneldata usermod '3F'      ",      " 24x80 24x80 basicds      " (4)      " delay 500      "      " signal off on logoff      " do forever address ispexec , (4)      " display panel(sesspan)      ",      " cursor(ptebuff) csrpos(     "ptecsrp     ")      " (5) if pfkey = ' ' then aid = 'enter' else aid = pfkey      " type usermod <&csrpos> aid &aid      " (6) if rc     /= 0 then leave end

SESSMAN Exec Notes:

  1. The name of an online system specified in a SESSMAN command is received by the SESSMAN exec as a REXX argument.
  2. CA Verify for CICS MONITOR and SIGNAL commands are used to display an error message if a requested session cannot be started.
  3. A CA Verify for CICS LOGON command is used to start a session with the named online system. The command specifies PANELDATA to instruct subsequent session commands to edit PTEBUFF for display using a session panel, and specifies USERMOD '3F' to inform CA Verify for CICS of the USERMOD value defined by the session panel.
  4. After the initial sign on screen is received by the DELAY command, the SESSMAN exec enters a DO loop that ends only when the session ends.
  5. An image of each display received at the virtual terminal is displayed at the TSO terminal using the ISPF DISPLAY command and a session panel like the panel shown in the following example. The DISPLAY command positions the cursor using the virtual terminal cursor position returned by session commands in variable, PTECSRP.
  6. A TYPE command that specifies the USERMOD keyword is used to rekey data entered by the terminal user into the virtual terminal display. USERMOD finds data in PTEBUFF that was entered by the user using the USERMOD value specified by the LOGON command and in the session panel definition. The TYPE command uses the ENTER key or the PF key pressed by the terminal user to send the input to the online system.
  7. The session and the SESSMAN exec end when the user enters a logoff transaction that causes the online system to end the session.

Monitoring Execs and Sessions

CA Verify for CICS commands are designed to automate terminal tasks and provide options that allow REXX execs to handle all possible errors and other events, and therefore, by default, do not automatically display error messages, exec-driven sessions or other command events. However, an exec or an exec user may use command monitoring functions built into CA Verify for CICS commands for REXX, to monitor selected events and to document, display or otherwise process errors, exec-driven sessions and other events automatically, while an exec is executing.

The CA Verify for CICS MONITOR command may be used in any exec to automatically display information about specified events while an exec is executing or to call a monitor exec to process the information:

MONITOR command VIASAY, VIATPUT and VIAEXEC options specify how monitored events are handled when they are detected. VIASAY and VIATPUT display events other than RESPONSES using the REXX SAY instruction or TSO TPUT, depending on the REXX environment in which the exec is executing. VIAEXEC calls a specified monitor exec when a monitored event is detected. When RESPONSES are monitored, a monitor exec is always called to process online system responses received by CA Verify for CICS session commands, either an exec specified by the VIAEXEC option or a default monitor exec.

When a monitor exec is called to process detected events, call arguments provide detailed information about the event to the monitor exec. Call arguments are explained in The Monitor Exec Interface. The monitor exec shown in The Distributed Monitor Exec VTEMONX is designed to be used as the default monitor exec that is called when RESPONSES are monitored but a VIAEXEC is not specified. When it is called to process an online system response to a transaction entered by an exec using the CA Verify for CICS TYPE command, VTEMONX uses either ISPF display services or the REXX SAY instruction to display a virtual terminal screen image, depending on the REXX environment in which the exec is executing.

A MONITOR command applies to all execs that execute in the REXX environment in which the MONITOR command is executed, and may be issued by a general purpose front-end exec that is used to call and monitor other execs with no modification to the called execs.

The distributed front-end exec, VTESMON, is shown in the following example. VTESMON may be used to call and monitor an exec in REXX environments created by ISPF, TSO or IRXJCL, with no modification to the called exec, by entering the following as a TSO command or as an IRXJCL PARM:

VTESMON testexec args

VTESMON issues a MONITOR command to monitor CA Verify for CICS commands issued by the called exec, testexec, relying on the default monitor exec, VTEMONX, to display response events. Both VTESMON and VTEMONX use either ISPF display services or the REXX SAY instruction to display events depending on the REXX environment. When a specified testexec returns, VTESMON reports any REXX condition caused by the call to testexec and ends any session not ended by testexec.

The following is an example of the VTESMON exec-driven session monitor:

     /* VTESMON - A Monitor for REXX-driven Verify Sessions (distributed) */          arg args          parse upper var args execname execargs          if execname = '' then do              say 'Enter: VTESMON execname (optional args for execname)'              exit              end          address Verify        " ACCESS EXECPORT " ; " QUERY SESSION "          if ptestate \= 'PTESTATE' then " LOGOFF "        " MONITOR SIGNALS RESPONSES "            signal on halt name halt     ; signal on error name error            signal on syntax name syntax ; signal on failure name fail            interpret "call '"execname"' '"execargs"'"            problem = ''                 ; signal finish      halt: problem = 'HALT'             ; signal finish     error: problem = 'ERROR'            ; signal finish    syntax: problem = 'SYNTAX'           ; signal finish      fail: problem = 'FAILURE'          ; signal finish    finish: signal off halt              ; signal off error            signal off syntax            ; signal off failure      " MONITOR OFF " ; " ACCESS LASTPORT " ; " QUERY SESSION "      parse source . . . . . . . addrspn .      if addrspn = 'ISPF' then do            green = '01'x ; red = '05'x ; blue = '11'x ; white = '15'x            PTEDESKT = ''            address ispexec            " control nondispl " ; " display panel(VTEPXMDT) "            zwinttl = execname 'execution ended on Port' PTEPORT            select                 when problem \= '' then                    PTEMWIN2 = left(red || execname || white,                                        || 'terminated; REXX condition(',                                        || red || problem || white || ').',72),                                        || right(blue || 'Press' || green,                                        || 'ENTER' || blue || 'to end test.',72)           when ptestate.pteaport \= 'PTESTATE.'PTEAPORT then                    PTEMWIN2 = left(red || execname,                                        || white || 'did not end Port' PTEAPORT,          'session. ' red'LOGOFF issued.',72),                                        || right(blue || 'Press' || green,                                        || 'ENTER' || blue || 'to end test.',72)           otherwise do                                      PTEMWIN2 = left(green || execname,                                        || white || 'ended normally.',72),                                        || right(blue || 'Test ending . . .',72)           " control display lock "                end              end           " addpop row(19) column(1) " ; " display panel(VTEPXMW2) "           address Verify " WAIT 800 "               end        else do           say copies('_',79) ; say ' '           select               when problem \= '' then                     say execname 'terminated; REXX condition(' problem ').'               when ptestate.pteaport \= 'PTESTATE.'PTEAPORT then                     say execname 'ended but did not end Port',                              PTEAPORT 'session. LOGOFF issued.'                     otherwise say execname 'ended normally.'                     end                   end               if ptestate.pteaport \= 'PTESTATE.'pteaport then " LOGOFF "