Application Programming Interface Commands

Some of the cacc commands are also application programming interface (API) commands. API commands simplify application and EXEC creation that use cacc features. Instead of prompting for responses, these commands let you provide all the information about the command itself.
vmx32besp
Some of the
CA VM:Secure
commands are also application programming interface (API) commands. API commands simplify application and EXEC creation that use
CA VM:Secure
features. Instead of prompting for responses, these commands let you provide all the information about the command itself.
Contents
API Commands
The following commands can be used as API commands in application programs or EXECs:
  • ADDENTRY
  • ADDMDISK
  • CHGMDISK
  • DELENTRY
  • DELETE
  • DELMDISK
  • DUPMDISK
  • ENROLL
  • GETENTRY
  • LOCK
  • MODIFY
  • REPENTRY
  • SCAN
  • TAG
  • UNLOCK
Because you can use these commands directly (interactively) or add them to executable functions, their results, as described in this section, vary predictably. This is true particularly of results based on default or assumed values, because the default or assumed values are always those of the user ID that submits the command for processing. For example, if you direct the output of a command to the virtual reader when you enter a command directly at your terminal, the output is sent to your own virtual reader; however, if you direct the output of a command to the virtual reader when you put this command in a program, the output is sent to the virtual reader of the user ID that submitted the program for execution.
Common API Command Options
Many of the
CA VM:Secure
API commands support similar processing options, which are described below. If one of these options is used differently for a particular command, then its difference is explained in the detailed description of that command.
Routing Messages
CA VM:Secure
API commands return messages that can be trapped. The default destination for messages is the terminal of the user ID that issued the API command (if the command is in a program, this is the user ID that ran the program), but you can use the following options to redirect messages to multiple destinations. The calling application can parse messages in a file or program stack and use their information for any purpose.
  • FILE [
    filename
    ]
    Places all informational and error messages generated by the API command in a CMS file on the issuing user’s A-disk.
    By default, the name of this CMS file is the name of the command that generated the messages (for example, ADDENTRY). The filetype is always RESULTS.
    To store the messages in a different file, specify that filename. If you do not specify a filename, the FILE option must be the last one on the command line.
    If a file with the name
    filename
    RESULTS A does not exist on the issuing user ID A-disk,
    CA VM:Secure
    creates it. If the file does exist,
    CA VM:Secure
    appends new messages to its end.
    You cannot use the FILE option with the NOWAIT option.
  • [
    MSG
    | NOMSG]
    Displays (MSG) or does not display (NOMSG) informational and error messages generated by the API command at the issuing user’s terminal.
  • [STACK]
    FIFO
    | LIFO]
    Places all informational and error messages in the issuing user’s program stack: in first-in, first-out (FIFO) order or last-in, first-out (LIFO) order.
    The STACK option cannot be used with the NOWAIT option.
  • [STEM
    stemname
    ]
    The named REXX stem variable does one of the following:
    • Supplies input parameters to the command
    • Returns command responses or query results from command execution
    Commands with a STEM option must be issued from a REXX program.
Running Commands in Disconnected Mode
Some API commands format information or write information to minidisks. These processes can take some time to complete. You can write your program or EXEC to either wait for the API command to finish before other work can be done from the issuing terminal, or to complete the work in a servant, allowing the issuing user ID to continue with other work.
Because a process running on a servant has no communication path to the issuing user ID’s virtual machine,
CA VM:Secure
sends all messages generated by the process to the servant. When an API command in the servant completes,
CA VM:Secure
sends the console file of the servant's activity to the issuing user’s reader queue.
One option is available on most API commands that can run the process on a servant:
  • [ Wait | NOWait ]
    Waits (WAIT) for the API command to finish processing before allowing the issuing user ID to continue or does not wait (NOWAIT) but runs the process on a servant so the issuing user ID can continue.
    The Servant Facility must be active for the NOWAIT option to work.
    The WAIT | NOWAIT option on an API command is ignored if you specify the NOFORMAT option on that API command, since NOFORMAT implies that there is no time-consuming command processing. The option is also ignored if you create a directory profile or a minidisk on T-DISK or V-DISK, since no time-consuming activity involving a minidisk actually occurs.
    The NOWAIT option cannot be used with the FILE or STACK option.