tpf_glWrite: Write an update to a format-2 global record

This function requests an update to an open format-2 global record.

Last updated

Added for PUT00.

Format


#include <tpf/c_f2glob.h>
int tpf_glWrite(int globaldesc, enum t_glopt options);

or


#include <tpf/c_f2glob.h>
int tpf_glWrite(int globaldesc, enum t_glopt options,
                long offset, long length);
globaldesc
The global descriptor returned on a previous call to the tpf_glOpen function, which represents the format-2 global record that is to be updated.
options
The options for the write operation. These options indicate whether the entire global record or only a part of it will be updated. One of the following options must be specified.
TPF_GLALL
Updates the entire global record.
TPF_GLPART
Updates only the specified part of the global record. If this option is specified, the offset and length parameters must be included.
offset
This optional parameter specifies the beginning offset into the global where the update will occur.
length
This optional parameter specifies the minimum length, in bytes, of the update. This parameter is required when offset is specified.

Normal return

A value of 0.

Error return

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

ETPFGLOB_BADDESC
The specified global descriptor does not reference a valid open format-2 global record.
ETPFGLOB_BADLENGTH
The length specified is beyond the end of the specified format-2 global record.
ETPFGLOB_BADOFFSET
The offset specified is beyond the end of the specified format-2 global record.
ETPFGLOB_BADOPTIONS
The options specified are not valid for tpf_glWrite.
ETPFGLOB_DELETED
The format-2 global record has been deleted, so no updates are allowed. The global is closed, but no updates are performed to the persistent copy of the global.
ETPFGLOB_NOUPDATES
The format-2 global record cannot be keypointed or synchronized and, therefore, no updates are allowed.
ETPFGLOB_READONLY
The format-2 global record was opened as read only. No updates are performed to the persistent copy of the global.
ETPFGLOB_REINIT
The format-2 global record has been reinitialized, so no updates are allowed.

Programming considerations

  • Calling this function may 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 request an update to z/TPF format-1 globals use the glob_update 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 less than 8 characters, it must be padded on the right with blanks.
  • If access to a previously opened format-2 global record is no longer required, the tpf_glClose function must be called instead of updating the global with the tpf_glWrite function.
  • The requested global will be updated based on the defined attributes of the global. For example, if the global is defined as keypointable, the z/TPF system will request a keypointing of the global; if the global is defined as synchronizable, the global will be filed to the database; however, no other processors in the z/TPF complex will be notified of the update until the global is unlocked with tpf_glCntl or closed with tpf_glClose.
  • The offset and length parameters are meaningful only when the global is defined as synchronizable; otherwise, these parameters will be ignored.

Examples

The following example updates a format-2 global record that was opened previously for reading and writing. 
#include <tpf/c_f2glob.h>
#include <errno.h>
#include <stdio.h>
#include <string.h>
⋮	
int	 rc;
int 	descriptor;
char *globRecord;
⋮
descriptor = tpf_glOpen ("_TPFAUX1", TPF_GLRDWR, &globRecord);
if (descriptor == -1)
{
      printf ("Got an error on global open - %d", errno);
      exit (0);
}

strcpy (globRecord, "THIS IS JUST A TEST");

rc = tpf_glWrite (descriptor, TPF_GLALL);
if (rc == -1)
{
     printf ("Got an error on global write - %d", errno);
     exit (0);
}
⋮

Related information

See z/TPF C functions overview for more information about z/TPF C/C++ language support.