_PGMCALL()--Call an IBM i Program for IBM PASE for i

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 IBM^® i PASE program. See the IBM PASE for i topic collection for more information about creating IBM PASE for i programs.

The _PGMCALL() function calls an IBM i program (object type *PGM) from an IBM PASE for i 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 IBM i program (object type *PGM) to call. target must be a 16-byte aligned IBM PASE for i 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 IBM i 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 IBM i program unless PGMCALL_NOMAXARGS is specified.

flags

(Input) Specifies options to control how the IBM i 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 IBM i 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 IBM i program linkage).

PGMCALL_DROP_ADOPT
(0x00000002)

Specifies that authorizations adopted by IBM i 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 IBM PASE for i signals will not interrupt the called IBM i program. Some system functions (such as select) can be interrupted by signals. Normally either an ILE signal or an IBM PASE for i signal can interrupt such an operation, but PGMCALL_NOINTERRUPT delays IBM PASE for i signal processing until control returns from the called IBM i program. This option has no effect on ILE signal handling.

PGMCALL_NOMAXARGS
(0x00000008)

Specifies that more than 255 arguments may be passed to the IBM i 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 IBM PASE for i CCSID to the job default CCSID and passes the converted (EBCDIC) strings to the IBM i program. The converted strings are stored in an internal system buffer, so any changes made by the IBM i program are not returned to the caller (by-value argument behavior).

PGMCALL_EXCP_NOSIGNAL
(0x00000020)

Suppresses signals for IBM i exceptions. This option causes the system to return a function result of -1 (and set errno to 3474) instead of raising a signal for any exception during the call. You can use the QMHRCVPM()--Receive Program Message for IBM PASE for i function specifying message type *EXCP to determine what exception occurred.

Authorities

Object Referred to

Authority
Required

IBM i program to call

Return Value

Most errors from _PGMCALL are reported with IBM i exception messages that are converted to IBM PASE for i signals unless ILECALL_EXCP_NOSIGNAL is specified. See IBM PASE for i Signal Handling for information about handling IBM i exceptions.

If no IBM PASE for i signal is sent, a function result of zero indicates the IBM i 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 IBM i-unique ILE errno EAPAR):

[EINVAL]

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

Usage Notes

_PGMCALL can only call IBM i program objects (object type *PGM). If your IBM PASE for i program needs to call a particular ILE procedure inside a *PGM or *SRVPGM object, you must to use the _ILECALL function.
You can use the _RSLOBJ or _RSLOBJ2 function to obtain a system pointer to an IBM i program (object type *PGM).
Arguments (addressed by pointers in the argv array) can be of any data type. Arguments are passed by-address, so the called IBM i program can modify argument variables to return results to the IBM PASE for i program unless PGMCALL_ASCII_STRINGS is specified.
_PGMCALL does no character encoding conversions unless PGMCALL_ASCII_STRINGS is specified,so the IBM PASE for i program may need to convert argument and result character strings between ASCII and EBCDIC. IBM PASE for i runtime function iconv can be used for character conversions.

Related Information

API introduced: V5R2

[ Back to top | IBM PASE for i APIs | APIs by category ]