tpf_glOpen: Open a z/TPF format-2 global record for read or write access

This function opens a z/TPF format-2 global record and returns a global descriptor.

Last updated

  • Changed for PUT14.
  • Changed for PUT08.
  • Added for PUT00.

Format


#include <tpf/c_f2glob.h>
int tpf_glOpen(char *globalname, enum t_glopt options,
               void **globaladdr);
globalname
The 8-byte name of the requested format-2 global record.
options
The options for the open operation. The options indicate whether the global record will be opened for reading, or for reading and writing. Specify one of the following values:
TPF_GLRD
Opened for reading only.
TPF_GLRDWR
Opened for reading and writing. The global will be locked for exclusive use by this entry control block (ECB).
TPF_GLRDFST
Opened for reading only by using the fast path. You can use this value when fast access is required. If you specify this value, the z/TPF system does not track the global as opened for this ECB.
TPF_GLRWTNLK
Opened for reading and writing. If you specify this value, the z/TPF system tracks the global as opened for this ECB; however, the global is not locked for exclusive use by the ECB. This value is valid only for format-2 global records that are defined as keypointable.
globaladdr
The location of where to store the address of the requested format-2 global record.

Normal return

  • If the requested function was successful and the TPF_GLRD, TPF_GLRDWR, or TPF_GLRWTNLK value was specified, an integer greater than zero is returned, which represents a global descriptor. This global descriptor must be supplied on subsequent tpf_gl function calls.
  • A value of 0 if successful and TPF_GLRDFST was specified.

Error return

If unsuccessful, tpf_glOpen returns a value of -1, a system error might be issued, and the errno C variable is set to one of the following values:

ETPFGLOB_BADNAME
The specified global does not indicate the name of a valid format-2 global record.
ETPFGLOB_BADADDR
The specified location of where to store the address of the requested format-2 global record was NULL.
ETPFGLOB_OPEN
The ECB already has the specified format-2 global record opened.
ETPFGLOB_BADOPTIONS
The options specified are not valid for the tpf_glOpen function.
ETPFGLOB_UNINIT
The specified global has not been initialized.
ETPFGLOG_NOTKYPT
The specified format-2 global record was not defined as keypointable.
ETPFGLOB_NOHEAP
There is not enough ECB heap storage to create a format-2 global descriptor.

Programming considerations

  • Calling this function might cause the ECB to give up control. Therefore, storage protection override must not be turned on when calling this function.
  • This function can be used only with z/TPF format-2 globals. To access z/TPF format-1 globals, use the glob function.
  • Unlike format-1 globals, the names of format-2 global records are the same in C language and basic assembler language (BAL). If the global name is fewer than 8 characters, it must be padded on the right with blanks.
  • When a format-2 global record is opened for reading and writing by using the TPF_GLRDWR value, the global is locked for exclusive use based on the defined attributes of the global. For example, if the global is defined as synchronizable, the equivalent of a synchronization lock is initiated to lock the global; if the global is defined as nonsychronizable and processor unique, the equivalent of a corhc function is issued to lock the global. The ECB can be forced to give up control during this processing.
  • When a format-2 global record is opened for reading and writing by using the TPF_GLRWTNLK value, the global record is not locked for exclusive use. Therefore, you must provide a method to serialize the updates to the global record.
  • Storage protection for the ECB is not changed. If the global record is defined as a protected global, a tpf_stpoc function must be issued by the application before the global can be changed by the ECB.
    Note: This might cause the ECB to give up control if the global record has not yet been loaded into main storage.
  • If you call the tpf_glOpen function from a dormant subsystem user (SSU), the function returns a GLOBRC_ERROR return code and sets errno to ETPFGLOB_UNINIT.

Examples

The following example opens the _TPFAUX1 format-2 global record for read-only access. 
#include <tpf/c_f2glob.h>
#include <errno.h>
⋮
int	rc;
char	*globRecord;
⋮
rc = tpf_glOpen ("_TPFAUX1", TPF_GLRD, &globRecord);
if (rc == -1)
{
     printf ("Got an error on global open - %d", errno);
     exit (0);
}
⋮

For more information about global areas, see z/TPF Application Programming, z/TPF Concepts and Structures, and z/TPF and z/TPFDF System Installation Support Reference.