oslink

oslink

Call an OS/390 Utility Program

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
PORTABILITY
IMPLEMENTATION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <os.h>

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

DESCRIPTION

oslink calls another load module (usually an OS/390 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. OS/390 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 OS/390 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 OS/390 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 OS/390.

IMPLEMENTATION

oslink uses the OS/390 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("IE

RELATED FUNCTIONS

popen , system