_PGMCALL()--Call an i5/OS Program for i5/OS PASE



  Syntax 
 #include <as400_protos.h>

 int _PGMCALL(const ILEpointer  *target,
              void              **argv,
              unsigned          flags);

  Default Public Authority: *USE

  Library: Standard C Library (libc.a)

  Threadsafe: Yes


Note: This function can only be used in an i5/OS PASE program. See i5/OS PASE for more information about creating i5/OS PASE programs.

The _PGMCALL() function calls an i5/OS program (object type *PGM) from an i5/OS PASE program. It transfers control to the *PGM object specified by a 16-byte tagged system pointer (passing any necessary arguments) and resumes execution when control returns.


Parameters

target
(Input) Pointer to a tagged system pointer that addresses the i5/OS program (object type *PGM) to call. target must be a 16-byte aligned i5/OS PASE memory address.

argv
(Input/Output) Array of pointers to arguments. argv is the address of an array of pointers to argument variables that are (usually) passed by-address to the i5/OS program. argv can be zero (null) if there are no arguments to pass. The last element in the array must be a null pointer. A maximum of PGMCALL_MAXARGS (255) arguments can be passed to an i5/OS program unless PGMCALL_NOMAXARGS is specified.

flags
(Input) Specifies options to control how the i5/OS program is called. The flags argument is a bitwise logical-or of one or more of the following values:

PGMCALL_DIRECT_ARGS
(0x00000001)		 Specifies that the addresses in the argv array are passed directly to the i5/OS program as formal arguments. If PGMCALL_DIRECT_ARGS is omitted, the system builds tagged space pointers to the argument memory locations identified in the argv array and passes the space pointers as formal arguments (standard i5/OS program linkage).
PGMCALL_DROP_ADOPT
(0x00000002)		 Specifies that authorizations adopted by i5/OS program invocations already in the stack are dropped so the called program only benefits from authorizations available to the user and group profiles for the thread.
PGMCALL_NOINTERRUPT
(0x00000004)		 Specifies that i5/OS PASE signals will not interrupt the called i5/OS program. Some system functions (such as select) can be interrupted by signals. Normally either an ILE signal or an i5/OS PASE signal can interrupt such an operation, but PGMCALL_NOINTERRUPT delays i5/OS PASE signal processing until control returns from the called i5/OS program. This option has no effect on ILE signal handling.
PGMCALL_NOMAXARGS
(0x00000008)		 Specifies that more than 255 arguments may be passed to the i5/OS program. Current system architecture limits the number of arguments to 16383 when this flag is set. Specifying PGMCALL_NOMAXARGS slightly increases system resource requirements even when no more than 255 arguments are provided.
PGMCALL_ASCII_STRINGS
(0x00000010)		 Specifies that all arguments are null-terminated ASCII character strings. The system converts argument strings from the i5/OS PASE CCSID to the job default CCSID and passes the converted (EBCDIC) strings to the i5/OS program. The converted strings are stored in an internal system buffer, so any changes made by the i5/OS program are not returned to the caller (by-value argument behavior).

Authorities

Object Referred to Authority
Required
i5/OS program to call *X


Return Value

Most errors from _PGMCALL are reported with i5/OS exception messages that are converted to i5/OS PASE signals. See i5/OS PASE Signal Handling for information about handling i5/OS exceptions.

If no i5/OS PASE signal is sent, a function result of zero indicates the i5/OS program was called and returned normally. A function result of -1 indicates an error that is further qualified by an errno value.


Error Conditions

At least these errno values can be returned, with other values also possible (such as i5/OS-unique ILE errno EAPAR):

[EINVAL] An invalid flags value was specified, or too many arguments were provided.


Usage Notes

  1. _PGMCALL can only call i5/OS program objects (object type *PGM). If your i5/OS PASE program needs to call a particular ILE procedure inside a *PGM or *SRVPGM object, you must to use the _ILECALL function.

  2. You can use the _RSLOBJ or _RSLOBJ2 function to obtain a system pointer to an i5/OS program (object type *PGM).

  3. Any i5/OS program that accepts arguments must be Teraspace-safe (created using TERASPACE(*YES)) to be called using _PGMCALL because the arguments are usually passed in Teraspace storage.

  4. Arguments (addressed by pointers in the argv array) can be of any data type. Arguments are passed by-address, so the called i5/OS program can modify argument variables to return results to the i5/OS PASE program unless PGMCALL_ASCII_STRINGS is specified.

  5. _PGMCALL does no character encoding conversions unless PGMCALL_ASCII_STRINGS is specified,so the i5/OS PASE program may need to convert argument and result character strings between ASCII and EBCDIC. i5/OS PASE runtime function iconv can be used for character conversions.


Related Information


API introduced: V5R2
Top | i5/OS PASE APIs | APIs by category