Directing commands

With the RACF® remote sharing facility (RRSF), you can direct most RACF commands to be processed on a node and user ID other than the one that you are logged on to. You can also direct a command to the user ID you are currently logged on to. Directed commands run asynchronously. That is, the command issuer does not wait until the command completes processing, and the results and output from the command is returned to the command issuer in a data set.

For a list of the commands that can be directed, see z/OS Security Server RACF Command Language Reference. For information about creating the user ID associations that are necessary to direct commands, see User ID associations.

You must have authorization to direct commands. If you are not sure whether you are authorized, contact your security administrator or see z/OS Security Server RACF Security Administrator's Guide for more information.

To direct RACF commands to be processed under the authority of an associated user ID without logging on to that ID, use the AT keyword. Add the AT keyword to the end of any eligible RACF command and specify the node and user ID (node.userid) at which the command should be processed. A user ID association is required for all commands that are directed to another node or user ID. However, it is not required if you are directing the command to the user ID that you are currently logged on to.

When you direct a command, the results are returned to you and are appended to the end of your RRSFLIST user data set. You receive a TSO SEND message that indicates whether the directed command has completed or failed. If you do not have an RRSFLIST user data set, RACF allocates one for you and adds the results to it. The RRSFLIST data set name is 'prefix.userid.RRSFLIST', where prefix is your TSO prefix at the time you issue the command. If prefix matches userid or if you specified PROFILE NOPREFIX on the TSO PROFILE command, the data set name that is used is 'userid.RRSFLIST'.

You are responsible for maintaining your RRSFLIST user data set. If your data set becomes full, or otherwise unusable, RRSF performs one of the following actions:

If you do not have READ access to profile RRSFLIST.FAILOVER.TRANSMIT in the RRSFDATA class:
- RRSF appends the command output to your RRSFLIST.OVERFLOW data set. If you do not have an RRSFLIST.OVERFLOW data set, RRSF allocates one for you and adds the results.
- RRSF continues to save all output, if any, to your RRSFLIST.OVERFLOW data set for a 20-second window.
  - After 20 seconds, RRSF will revert to saving to your RRSFLIST data set. If your RRSFLIST data set is still full or unusable, the process repeats.
  - If your RRSFLIST.OVERFLOW data set is also full or unusable, RRSF discards all output for a 20-second window.
  - After 20 seconds, RRSF will revert to saving to your RRSFLIST data set. If your RRSFLIST data set is still full, the process repeats.
- TSO SEND messages are issued to explain why output is being routed to your RRSFLIST.OVERFLOW data set or is being discarded. This message is issued only once per each 20-second time window. The first output that is written to your RRSFLIST.OVERFLOW data set is preceded by a message that explains why it was saved there instead of to your RRSFLIST data set.
- The overflow and discard time windows are independent of one another. It is possible to be outside the overflow window, but still within the discard window. Given the limitation of one error notice per window, this behavior can lead to situations in which a new overflow window is entered when the previous discard window is still in effect. For example:
```
IRRR024I User data set IBMUSER.RRSFLIST is full. 
IRRR022I IBMUSER.RRSFLIST is not usable. Switching to IBMUSER.RRSFLIST.OVERFLOW for 20 seconds. 
IRRR011I LG was successful at node NODE1. Output was lost.
```
  Here, RRSF attempts to write to the user’s RRSFLIST data set, discovers that it is full, and triggers the 20-second overflow window. However, a previously triggered 20-second discard window is still in effect. Because RRSF notifies the user only at the initial triggering of the window, no additional message is sent to indicate that the user’s RRSFLIST.OVERFLOW data set is also unavailable. This situation leads to the command output ultimately being discarded, as indicated by the IRRR011I message.
- Your RRSFLIST or RRSFLIST.OVERFLOW data set is considered unsuable if it is in use by another program, such as being browsed in ISPF.
- Do not simultaneously allocate both RRSFLIST and RRSFLIST.OVERFLOW unless you are certain that no output is expected from RRSF.
If you have READ access to profile RRSFLIST.FAILOVER.TRANSMIT in the RRSFDATA class, or if the RRSFLIST.FAILOVER.TRANSMIT profile does not exist, note the following:
- RRSF uses TSO TRANSMIT to send the command output to you. The output begins with a message that indicates that your RRSFLIST data set was full at the time the output was received.
- If your RRSFLIST data set is in use, RRSF waits a brief time and tries again. If your RRSFLIST data set remains in use for a long period, and you have many output records to receive, RRSF might encounter constraint issues with storage or the INMSG VSAM workspace data set.

Start of change You are responsible for preventing your RRSFLIST data set from becoming full. It is recommended that you periodically delete data when it is no longer needed. End of change

If you want more control over the characteristics of the RRSFLIST data set, you can allocate your own before RRSF writes any data. The data set must have the following attributes:

Record format (RECFM): Fixed block (FB)
Logical record length (LRECL): 80
Data set organization (DSORG): Physical sequential (PS).

Examples of directed command output

The following examples illustrate the format of the output that is produced by directed commands. The format of the output is the same for both your RRSFLIST data set and for the output that is transmitted when your data set is full.

The following example shows a directed LISTGRP command:

LISTGRP (SYS1) AT(MVS03.SMITHJ)

Figure 1 shows the format of output for this directed LISTGRP command.

Figure 1. A directed LISTGRP command: sample output

LG issued at 09:14:32 on 02/02/98 was processed at MVS03.SMITHJ on
02/02/98 at 09:16:24

 COMMAND ISSUED: LISTGRP   (SYS1)

 COMMAND OUTPUT:
 INFORMATION FOR GROUP SYS1
     SUPERIOR GROUP=NONE         OWNER=SMITHJ
     NO INSTALLATION DATA
     NO MODEL DATA SET
     TERMUACC

The following example shows a directed ADDSD command:

ADDSD 'JWS.DEV*' AT(MVS02.JWS)

Figure 2 shows the output for this directed ADDSD command.

Figure 2. A directed ADDSD command: sample output

ADDSD issued at 09:47:32 on 02/02/98 was processed at MVS02.JWS on
02/02/98 at 09:48:51

 COMMAND ISSUED: ADDSD        'JWS.DEV*'

 COMMAND OUTPUT:
 IRRR008I Command succeeded.  There are no messages.