The Synchronous Application Programming Interface (SAPI)

The DIRMSAPI EXEC is an example of a REXX program that sets up the proper environment for using the SAPI interface. The DVHSAPI EXEC issues a command to the DIRMAINT service machine and waits for the response, which it passes back to DIRMSAPI EXEC. Both of these sample exec files reside on the user interface disk (4VMDVH10 11F, by default) as file names DIRMSAPI EXECSAMP and DVHSAPI EXECSAMP. These files are available for your examination.

Given a DirMaint command string, the DIRMSAPI EXEC routine calls the DVHSAPI EXEC to send the command to the DIRMAINT service machine and wait for the responses from the service machine. The responses are returned from DVHSAPI in the DVHSAPI. stem variable.

The DVHSAPI EXEC routine is not intended to be invoked as a command directly from the console. It is intended to be called by a customer supplied REXX program. The DIRMSAPI EXEC (or DIRMSAPI EXECSAMP file) is a sample of such a program.

The following rules have been applied to the DIRMSAPI EXEC sample.

• An EXEC DIRMAINT EXECLOAD command should be issued before calling DVHSAPI, and an EXEC DIRMAINT EXECDROP command should be issued when no further calls to DVHSAPI are anticipated for a significant time interval. When issuing multiple commands, a single EXEC DIRMAINT EXECLOAD command should be used before the group of calls to DVHSAPI, and one EXEC DIRMAINT EXECDROP command should be used after the group. Service machines that frequently issue DIRMAINT commands should include an EXEC DIRMAINT EXECLOAD command in their PROFILE EXEC.
• If the PRESET global variable, in the DVH15 pool, has a value other than blanks or NOLOG, DirMaint will send that value to the DIRMAINT server without prompting for a password. To prevent disclosure of that password, the variable will be reset to a value of NOLOG upon exit, thus the value must be set prior to each call to the DIRMAINT EXEC.
  Note: If an EXEC DIRMAINT EXECLOAD command has already been issued and the files are still loaded, it is prudent to issue an EXEC DIRMAINT EXECDROP command before re-issuing the EXEC DIRMAINT EXECLOAD command. It does no harm to always issue an EXEC DIRMAINT EXECDROP command before issuing any EXEC DIRMAINT EXECLOAD command.

  /* Miniature sample for use of DVHSAPI. */
  Address 'COMMAND'
  Trace 'C'
  'EXEC DIRMAINT EXECLOAD'
  'EXEC DVHSAPI FOR USER1 DISTRIB NEWDIST1'
  'PIPE STEM DVHSAPI. | CONSOLE'
  'EXEC DVHSAPI FOR USER2 DISTRIB NEWDIST2'
  'PIPE STEM DVHSAPI. | CONSOLE'
  'EXEC DVHSAPI FOR USER3 DISTRIB NEWDIST3'
  'PIPE STEM DVHSAPI. | CONSOLE'
  'EXEC DVHSAPI FOR USER4 DISTRIB NEWDIST4'
  'PIPE STEM DVHSAPI. | CONSOLE'
  'EXEC DIRMAINT EXECDROP'
  Exit

• Calls to DVHSAPI may optionally preface the request with a time-out limit between 10 seconds (+00:00:1) and just under 12 hours (+11:59:5). The default is 15 seconds (+00:15), if not specified.
• The return code from DVHSAPI indicates the status of your request.

  1191

  Message DVH1191I was expected but not received. Your command has not been sent to the DIRMAINT service machine. The messages passed back in the DVHSAPI stem variable explain why.

  1196

  The DVHSAPI EXEC exceeded the interval second time limit while expecting message DVHnnnn. The responses in the DVHSAPI stem variable are incomplete.

  2288

  Message DVH2288I was expected but not received. The DIRMAINT service machine received your request, but has rejected it from further processing. The messages passed back in the DVHSAPI stem variable explain why.

  2289

  Message DVH2289E was received. The DIRMAINT service machine processed your request, which ended with a non-zero return code. The messages passed back in the DVHSAPI stem variable explain why.

  0

  Message DVH2289I was received. The DIRMAINT service machine processed your request, which ended with a zero return code. The DVHSAPI stem variable will contain the messages, if any, generated while processing your request.

  xxxx

  Other non-zero return codes indicate one of three things:

  1. The DIRMAINT service machine failed to respond to your request within the allotted time interval; or
  2. The DVHSAPI EXEC was confused by messages from the DIRMAINT service machine generated by a previous request, or by spontaneous messages from the DIRMAINT service machine; or
  3. Some other error condition was encountered that the DVHSAPI EXEC could not handle.

• Be aware that some commands result in asynchronous processing. For example, an EXEC DVHSAPI +00:05:0 BATCH SETALL MYPWS command will send the contents of the SETALL MYPWS file to the DIRMAINT service machine for processing, with message DVH2289I and a zero return code indicating that the file has been received and appended to the batch queue for processing. A zero return code from DVHSAPI in this case does not indicate that any or all of the requests within the file have been processed, or that they will all be processed successfully. For example, if one of the records in the file is FOR DVHTEST PW DVHTEST, this request will very likely fail with message DVH2924E, even though you have already received message DVH2289I and a zero return code from your BATCH command.
• The DVHSAPI_END_MSG. CONFIG* DATADVH entry can be used to identify when the DVHSAPI routine exits and returns control back to the calling application. The default is to end when message DVHREQ2289I is received and no DVHSAPI_END_MSG. entries are specified. The sample CONFIG SAMPDVH file contains these entries:
  • DVHSAPI_END_MSG.DVHSCU3541I= DVHREQ2289I DVHSHN3430I
  • DVHSAPI_END_MSG.DVHPUR3370I= DVHREQ2289I DVHXXX3525I

  The message DVHSAPI_END_MSG.DVHSCU3541I= DVHREQ2289I DVHSHN3430I tells DVHSAPI that if it receives the message DVHSCU3541I, it should wait for both message DVHREQ2289I and DVHSHN3430I to be received, in any order, before determining whether the command finished successfully.

  You can use XXX for the issuing module ID portion of any ending message identifier (i.e. after the equal sign) to indicate that the message may be issued from any module/EXEC. For example, the statement:

  DVHSAPI_END_MSG.DVHPUR3370I= DVHREQ2289I DVHXXX3525I
  tells DVHSAPI that if it receives the message DVHPUR3370I, it should wait for both message DVHREQ2289I and for any message that begins with DVH and ends with 3525I before determining whether the command finished successfully.
  Note: This configuration entry can be used for any other condition requiring multiple messages to be received when determining if the command completed successfully.
• The DVHSAPI EXEC does not support use of the TOsys or TOnode prefix operand for remote networking. When used within a multi-system CSE cluster, cross-system SMSG capability must be enabled.