gtpc2m3v | C/C++ Language Support User's Guide |
This function is used to lock a program in core or locate a program either
in core or on file.
Format
#include <tpfapi.h>
int getpc(const char *name, int lock, enum t_lvl level,
void *core_addr, int error, int id,
const char *loadset);
- name
- A pointer to the character representation of the program name. The
name is 4 alphanumeric characters that should have been allocated at system
generation time. The program must be nonprivate.
- lock
- This argument is treated as an integer describing whether the program
should be locked in core. Use the defined terms GETPC_LOCK
to lock the program in core, GETPC_SPECIAL to lock the program in
core and mark it as special, or GETPC_NOLOCK to locate a program
but not lock it in core.
- level
- One of 16 possible values representing a valid data level from the
enumeration type t_lvl, expressed as Dx, where x represents
the hexadecimal number of the level (0-F). This indicates which
ECB FARW should be initialized with the program's file address and record
ID. NO_LVL can be specified if the file address is not
required.
- core_addr
- Receives the core address of the program.
- error
- This argument is treated as an integer describing whether control should
be returned to the caller on an error or if an OPR-066 should be
issued. Use the defined term GETPC_NODUMP to denote that
control should be returned to the caller, or GETPC_DUMP to denote
that the service routine should issue an OPR-066. The possible errors
are: the program name could not be found, the program name was found but
the loadset name could not be found, the program is allocated as private, or
the program already has the special indicator set.
- id
- Indicates which MDBF index will be used for running this function.
Use the defined term GETPC_PBI to denote that the program base ID
should be used, or GETPC_DBI to denote that the database ID should
be used. GETPC_DBI is not valid when coded with
GETPC_LOCK.
- loadset
- A pointer to a valid loadset name or BASE if referring to the
base-allocated program. If this parameter is used, the active program
that is associated with the specified loadset is affected. If this
parameter is specified as NULL, the version of the program associated with the
requesting ECB is affected.
Normal Return
0
Error Return
A nonzero error return code, as follows in Table 9.
Table 9. getpc Error Return
Numbers
| Return Code
| Description
|
#define GETPC_SNAPC_ERR
| 4
|
|
#define GETPC_LS_NF
| 8
| LOADSET VERSION NOT FOUND
|
#define GETPC_SP_SET
| 16
| SPECIAL LOCK NOT/ALREADY SET
|
#define GETPC_RETRIEVE_ERROR
| 32
| PROGRAM RETRIEVAL ERROR
|
#define GETPC_PRIVATE
| 64
| PROGRAM IS A PRIVATE PROGRAM
|
#define GETPC_PGM_NF
| 128
| PROGRAM NOT FOUND
|
Programming Considerations
- Only nonprivate programs can be locked in core.
- This function is not valid for C-type programs.
- Only 1 program at a time may be locked through this function.
Separate requests must be made for each program required.
- When GETPC_NOLOCK is specified, either the level
parameter or the core_addr parameter must be specified.
- When the program is no longer needed in core it should be unlocked using
the relpc function.
- When GETPC_SPECIAL is specified on the lock
parameter of the getpc function, RELPC_SPECIAL must be specified on
the unlock parameter of the relpc function.
Examples
The following example obtains the file address of program QZZ0 on data
level A, and the program's core address also. The information is
obtained using the PBI. If an error occurs, the service routine should
issue an OPR-066.
#include <tpfapi.h>
unsigned int pgm_core_addr;
struct pat *base_pat;
·
·
·
getpc("QZZ0",GETPC_NOLOCK,DA,&pgm_core_addr,GETPC_DUMP,GETPC_PBI,
NULL );
·
·
·
Related Information
relpc-Release Program from Core Lock.