gtpc2m1tC/C++ Language Support User's Guide

enqc-Define and Enqueue a Resource

This function defines a shared resource to the control program. It also controls access to the resource among entry control blocks (ECBs). This function is used with the deqc function.

Format

include   <tpfapi.h>
int       enqc(char            *enq_name,
               enum e_wait     enq_wait,
               unsigned long   timeout,
               enum e_qual     ssu_qual);

enq_name
The address of an 8-byte area that contains the enqc resource name.

enq_wait
Indicates whether the ECB is forced to wait. The argument must belong to the enumerated type e_wait, which is defined in the tpfapi.h header file. Use one of the predefined terms:

ENQ_WAIT
If specified, the ECB is forced to wait before gaining control of the resource.

ENQ_NOWAIT
If specified, the ECB will not give up control if the named resource is already in use by another ECB.

timeout
An integer specifying the number of seconds that the ECB expects to hold the resource. The value can be specified with a range of 0-65 535. The timeout does not start until there is another ECB waiting. If the specified time elapses, the ECB will exit with a system error. If 0 is specified, the timeout function is turned off.

ssu_qual
Subsystem qualification for the resource. The argument must belong to the enumerated type e_qual, which is defined in the tpfapi.h header file. Use one of the following predefined terms:

QUAL_U
Subsystem qualification applies. The resource name is subsystem user (SSU) unique and is qualified by the database index (DBI) value for the subsystem.

QUAL_S
System wide qualification applies. The resource name is not subsystem unique. Any ECB that issues the enqc function with QUAL_S will be enqueued on the same named resource. If two enqc functions are issued with the same resource name but different ssu_qual values, two different resource names are assumed to exist. The deqc function must have the same ssu_qual value as the enqc function.

Normal Return

ENQ_WAIT
Return code ECB_WAITED is returned if the resource was held by another ECB and the calling ECB has waited for the resource. Otherwise, return code 0 is returned.

ENQ_NOWAIT
An integer value of zero is returned if the calling ECB gains control of the named resource. An integer value of 1 (RESOURCE_IN_USE) is returned if the resource is already in use. The calling ECB will not give up control, but the ECB will not own the resource.

Error Return

None.

Programming Considerations

Examples

The following example defines and tries to gain access to a shared resource with a timeout value of 250 seconds and an ssu_qual of QUAL_S. The ECB will not wait if the the resource is in use by another ECB.

#include <tpfapi.h>
char    resource_name[8];
enqc(resource_name, ENQ_NOWAIT, 250, QUAL_S);

Related Information

deqc-Dequeue from Resource.