oslink -- Call an MVS Utility Program

SYNOPSIS

 #include <os.h>

 int oslink(const char *pgm, arg1, arg2 ...);
 

DESCRIPTION

oslink calls another load module (usually an MVS utility program), passing one or more arguments. The load module, whose name is specified by pgm, must be in the same library as the C program (in STEPLIB) or the link list or link-pack area. MVS standard linkage passes the arguments to the program; the high-order bit is set to indicate the last argument value in the list. (To avoid confusion produced by this bit, all program arguments should be defined as pointers.)

Most MVS utilities expect to receive two arguments, an option list, and a DDname list. See EXAMPLE for an example of this usage.

RETURN VALUE

The completion code returned by the called load module is returned by oslink. If the program cannot be called successfully, a negative value is returned. The negative return codes have the same meanings as the negative return codes from the system function.

CAUTION

oslink is used primarily to invoke MVS utility programs. Do not use it in place of loadm to dynamically load and execute C subordinate load modules because this produces an ABEND of the called module. You can use oslink to invoke a C main program, but invocation is more easily performed using the system function.

When oslink is used in MVS/XA or MVS/ESA by a program that runs in 31-bit addressing mode to call a program that runs in 24-bit addressing mode, all the arguments must be addressable using a 24-bit address. If the arguments are automatic, this is always true.

If a TSO attention interrupt occurs during a call to oslink, the called program is immediately terminated, unless the program handles the attention itself.

PORTABILITY

oslink is implemented only under MVS.

IMPLEMENTATION

oslink uses the MVS ATTACH macro to call the requested load module. This macro permits the C program to continue execution if the called program terminates abnormally.

EXAMPLE

This example for oslink invokes the IBM PL/I compiler, passing a list of options and a list of alternate DDnames. See the PL/I Programmer's Guide for further information.
  #include <os.h>
  #include <string.h>

     /* PL/I compiler options structure                  */
  struct {
     short optlen;
     char options[100];
     }  pli_opts;

    /* PL/I DDname list                                  */
  struct {
     short ddsize;
     char ddnames[8][8];
     }  pli_ddns;

  int plirc;                /* PL/I compiler return code */

     /* Build options parm.                              */
  strcpy(pli_opts.options, "SOURCE,NEST,XREF");
  pli_opts.optlen = strlen(pli_opts.options);

     /* Store size of DDnames.                           */
  memset(pli_ddns.ddnames, '0', sizeof(pli_ddns.ddnames));
  pli_ddns.ddsize = sizeof(pli_ddns.ddnames);

     /* Set alternate names. */
  memcpy(pli_ddns.ddnames[0], "ALTLIN  ", 8);
  memcpy(pli_ddns.ddnames[3], "ALTLIB  ", 8);
  memcpy(pli_ddns.ddnames[4], "ALTIN   ", 8);
  memcpy(pli_ddns.ddnames[5], "ALTPRINT", 8);
  memcpy(pli_ddns.ddnames[6], "ALTPUNCH", 8);
  memcpy(pli_ddns.ddnames[7], "ALTUT1  ", 8);

     /* Call compiler; save return code.                 */
  plirc = oslink("IEL0AA", &pli_opts, &pli_ddns);

 

RELATED FUNCTIONS

popen, system

SEE ALSO


Copyright (c) 1998 SAS Institute Inc. Cary, NC, USA. All rights reserved.