[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPINAP - Initiate Application Process

GPINAP (apid, ncid, size, namel, name, parmt, parml, parm)

Purpose

Use GPINAP to create an application process on a 6090.

System memory of the specified size is allocated, the specified program module is loaded into the memory and the module is started with the specified parameter data being passed.

This subroutine is applicable only to a nucleus running on a 6090. The program module must reside on a disk that is accessible from the shell as a single file with a format that can be loaded by the control program in the 6090. For details of the file format, see The graPHIGS Programming Interface: Technical Reference

Parameters

apid -- specified by user, fullword integer

Application process identifier.

ncid -- specified by user, fullword integer

Nucleus identifier. The specified nucleus must be running on a 6090.

size -- specified by user, fullword integer

Size of the memory allocated for the application process in bytes (>0) The size must be large enough to contain the program module itself and all storage used by the application process.

namel -- specified by user, fullword integer

Length of the file name in bytes (0<namel<=80)

name -- specified by user, character string

Name of the file that contains the program module of the application process. This parameter looks like a Unix AIX file descriptor which consists of a [path]/filename[extension] Path is the route of directories through the file system on an AIX system. It is optional and is ignored for MVS and VM.

Following is an example of a full file descriptor:

/dap/appl1.o

  • path = /dap which says go from the root directory to directory dap

  • filename = appl1

  • extension = .o

    • The following rules apply to the name parameter depending on which system the shell is running:

  • AIX

    If you do not specify the path, then the graPHIGS API uses the default directory at the time of the execution of the subroutine.

  • MVS, MVS/XA

  • filename - The filename must be supplied and it is a member name within a partition data set if the extension is included. If the extension is not included, then the filename is the DD-name of the partition data set.

  • extension - The extension is optional. If specified it is the DD-name of the partition data set including the member filename.

  • VM/CMS

  • filename - The filename must be supplied.

  • extension - The extension is optional. If it is not included an extension of .COF will be used.

  • the filename.extension will be folded to upper case.

    • parmt -- specified by user, fullword integer

    Format of the parameter data and method of passing it to the 'main' entry point of the application process. The following options are available:

    0 =

    No parameters are to be passed to the application process. Parameters parml and parm are ignored.

    1 =

    The parameter data consists of a single string. This string will be split into strings which contain no white space (blanks, newline, tabs, etc.) before being passed to the application process. The application entry point will receive two parameters. The first parameter will contain the number of strings resulting from the parsing operation described above. The second parameter will contain a list of pointers to each of the strings. The main entry declaration could be coded in "C" as follows: 
          void main( argc, argv )
         int    argc;
         char * argv[[default]

    2 =

    The parameter data contains arbitrary information which has content that is only understood by the application processes. A pointer to the data and the amount of data is passed to the application process when it is started. The main entry declaration could be coded in "C" as follows: 
          void main( parmlen, parmptr )
         int    parmlen;
         char * parmptr;

    Note:

    For this option, it is the application's responsibility to perform character code, floating-point, and byte order conversion between the two environments in which the application processes are executing.

    parml -- specified by user, fullword integer

    Length of data to be passed to the process as its invocation parameter in bytes (>=0)

    parm -- specified by user, variable length character or byte string

    Data to be passed to the process as its invocation parameter. The format of the data contained in this parameter is defined by parmt

    Error Codes

    202
    SPECIFIED NUCLEUS DOES NOT EXIST
    1301
    SPECIFIED APPLICATION PROCESS ID ALREADY IN USE
    1303
    SIZE OF APPLICATION PROCESS REGION IS TOO LARGE
    1304
    APPLICATION PROCESS REQUEST EXCEEDS NUCLEUS CAPACITY
    1305
    LENGTH OF APPLICATION MODULE NAME IS INVALID
    1307
    APPLICATION MODULE HAS UNRESOLVED EXTERNAL REFERENCE a1
    1308
    PARAMETER TYPE IS INVALID
    1309
    PARAMETER LENGTH < ZERO
    1310
    APPLICATION MODULE SIZE > REGION SIZE
    1311
    APPLICATION LOAD MODULE IS INVALID
    1316
    APPLICATION PROCESS ID=n1 EXITED WITH CODE=n2

    Related Subroutines

    GPEXAP
    Execute Application Process
    GPTMAP
    Terminate Application Process
    GPQNCE
    Inquire Nucleus Environment

    RCP code

    201342465 (X'0C003E01')

    [ Previous | Next | Contents | Glossary | Home | Search ]