 |
Purpose The MIBConnect
function returns a link identifier that is used to refer to the connection
in future calls to the API.
The MIBConnect function is a synchronous
function. The return code from the MIBConnect function indicates whether
the function completed successfully.
The MIBConnect function
opens an ACB on behalf of the caller. The ACB is closed when the caller
calls the MIBDisconnect function or when the task that called the
MIBConnect function terminates. The ACB is not closed when CMIP services
terminates or when VTAM® terminates.
Declarations The following
declarations indicate the order of the parameters for this function.
typedef int MIBConnect_t(
unsigned int, /* API level - input */
int *, /* link identifier - output */
unsigned int, /* maximum outstanding invoke
identifiers - input */
const char *, /* application ACB name - input */
void *, /* TPEND routine pointer - optional input */
void *, /* read queue exit routine pointer - input */
unsigned int *, /* SMAE name buffer size - input/output */
char *, /* SMAE name buffer - output */
unsigned int *, /* System Object name buffer size -
input/output */
char *, /* System Object name buffer - output */
int, /* user data - input */
unsigned int *, /* OPEN ACB error value - output */
char **, /* VTAM release level - output */
const char *, /* password - optional input */
unsigned int, /* data space vector length - optional input */
ISTRIV10_t *, /* data space vector - optional input */
unsigned int, /* local identifier length - input */
unsigned int); /* connection options - input */
Parameters - API level
- This
parameter must be 0.
- link identifier
- MIBConnect
returns a value in this field. The application program must provide
this value in subsequent API calls.
- maximum outstanding invoke identifiers
- This
parameter determines how many unique invoke identifiers can be generated
locally by the API. Invoke identifiers are generated on all requests
that are sent to CMIP services and can be reused once the response
has been received by the requestor. API functions generate and clear
invoke identifiers. The caller of the API function does not need to
generate or keep track of outstanding invoke identifiers except where
needed for its own request/response correlation.
Note: Valid values
are 256 to 65535. Input values are changed to meet the minimum or
maximum range.
- application ACB name
- This
parameter is a pointer to a null-terminated string that represents
the unique name associated with application. The name must be unique
among VTAM resources and must
be defined on the APPL definition statement. It must follow the naming
rules that apply to application programs that open an ACB.
Note: The value of this parameter
is converted to uppercase before being passed to OPEN ACB.
- TPEND routine pointer
- This
parameter is the address of an application assembler routine to be
called by VTAM if VTAM terminates before the application program
terminates or issues the MIBDisconnect function. Specify NULL if you
do not wish to provide a termination exit routine.
See z/OS Communications Server: SNA Programming for information about the TPEND exit routine.
As
with other TPEND exit routines, the application program should clean
up in an orderly manner for a normal HALT command. The application
program should deregister objects, discard EFDs, and disconnect.
In
response to a HALT QUICK or HALT CANCEL command, the application program
should not attempt to clean up. It should only issue the MIBDisconnect
function.
Note: The ACBUSER field are set to the value of the
user data parameter supplied on the MIBConnect function when the TPEND
exit routine is scheduled.
- read queue exit routine pointer
- This
parameter is the address of an application assembler routine to be
called by CMIP services when
messages are to be received. See Read queue exit routine for
information about the read queue exit.
- SMAE name buffer size
- This
is the size of the buffer provided by the application for the SMAE
name. 100 bytes is the recommended size for this buffer.
MIBConnect
is set the value to the actual length (including the terminating zero)
on output.
If the buffer provided is not long enough, MIBConnect
returns the MB_ERR_STORAGE_TOO_SMALL return code. The application
should allocate a new buffer using the updated value of this parameter
and call MIBConnect again.
- SMAE name buffer
- MIBConnect
places a pattern for building SMAE names in the storage pointed to
by this parameter. The application program can use this pattern with
the C Standard Library function sprintf to build the name
of a SMAE name on this host.
The following example SMAE name format
as returned by MIBConnect: 1.3.18.0.2.4.6=NETA;2.9.3.2.7.4=(name SSCP1A);1.3.18.0.2.4.12=%s
Assuming
that format is the name of a character array containing the format
string and AE is the name of a character array to hold the resulting
SMAE name, the following code will build a SMAE name that could be
used for the RegisterAE special CMIP Services request. sprintf(AE,format,"MyApplName");
The
name of the default SMAE provided by CMIP Services has OSISMASE as
the final attribute value in the distinguished name.
- System Object name buffer size
- This
is the size of the buffer provided by the application for the System
Object. The recommended size for this buffer is 100 bytes.
MIBConnect
sets the value to the actual length (including the terminating zero)
on output.
If the buffer provided is not long enough, MIBConnect
returns MB_ERR_STORAGE_TOO_SMALL. The application program should then
allocate a new buffer using the updated value of this parameter and
call MIBConnect again.
- System Object name buffer
- MIBConnect
places the name of the System Object into this buffer.
The System
Object name should be used when creating local EFDs; EFDs are named "under" the
System Object.
- user data
- This
four-byte field is provided to the application program on entry to
the read queue and to the TPEND exit routines.
- OPEN ACB error value
- When
control is returned to the application program and the return code
is MB_ERR_CONNECT, the OPEN ACB error value parameter needs to be
evaluated.
The following list shows the OPEN ACB error values
returned in the OPEN ACB error value parameter. - ERROR Field
- Meaning
- 0 (X'00')
- OPEN successfully opened this ACB.
- 4 (X'04')
- The ACB has been opened.
- 20 (X'14')
- OPEN cannot be processed because of a temporary shortage of storage.
- 36 (X'24')
- The OPEN ACB failed for one of the following reasons:
- The password specified by the ACB did not match the corresponding
password in the APPL entry.
- The ACB did not specify a password and the APPL contains one.
- The
security management product determined that the user is not authorized
to open the ACB.
- 70 (X'46')
- OPEN was issued in an exit routine.
- 80 (X'50')
- VTAM has not been included
as part of the operating system. The fault lies in the system definition
procedures.
- 82 (X'52')
- VTAM is included as part
of the operating system, but the VTAM operator
issued a HALT command, and VTAM has
shut down. You cannot attempt to establish a session or communicate
with any LUs.
- 84 (X'54')
- Either the address supplied in the ACB's APPLID field lies beyond
the addressable range of your application program, or no entry is
found in the VTAM configuration
tables that matches the name indicated by the ACB's APPLID field (or
supplied by the operating system). If the OPEN macroinstruction is
specified correctly, your system programmer might have:
- Failed to include your application program's symbolic name during VTAM definition
- Improperly handled the symbolic name
Refer to the description of the APPLID operand in the ACB macroinstruction.
- 86 (X'56')
- A match for your application program's symbolic name is found,
but it is for an entry other than an APPL. If you specified this name
in the ACB's APPLID field, verify that you have the correct name and
handled this name properly (see the APPLID operand of the ACB macroinstruction).
If the symbolic name is supplied by the operating system, the supplied
name is suspect.
- 88 (X'58')
- Another ACB, already opened by VTAM,
indicates the same application program symbolic name that this ACB
does. The system programmer might have assigned the same symbolic
name to two application programs. This is valid only if the programs
are not open concurrently. Possibly the system operator initiated
your program at the wrong time.
- 90 (X'5A')
- No entry is found in the VTAM configuration
tables that matches the name indicated by the ACB's APPLID field (or
supplied by the operating system). This error might have occurred
for one of the following reasons:
- The VTAM operator deactivated
the APPL entry.
- The APPL entry was never created.
- If VTAM is trying to recover
for persistent sessions, the application is not in pending recovery
state.
- 92 (X'5C')
- VTAM is included as part
of the operating system but inactive.
- 94 (X'5E')
- The address supplied in the ACB's APPLID field lies beyond the
addressable range of your application program.
- 95 (X'5F')
- The VTAM transient being
used by the application for an OPEN ACB does not match the level of VTAM.
- 96 (X'60')
- An apparent system error occurred. Either there is a logic error
in VTAM, or there is an error
in your use of OPEN or CLOSE that VTAM did
not properly detect. Save all applicable program listings and storage
dumps, and consult IBM® Service.
- 98 (X'62')
- The APPLID length byte is incorrectly specified.
- 100 (X'64')
- The address supplied in the ACB's PASSWD field lies beyond the
addressable range of your application program.
- 102 (X'66')
- The PASSWD length byte is incorrectly specified.
- 104 (X'68')
- The APPLID field in the ACB identifies an application program
that is defined with AUTH=PPO in its APPL definition statement. Another
program with the same authorization is active. Only one program defined
with AUTH=PPO can be active at a time.
- 106 (X'6A')
- The address supplied in the ACB's vector list field lies beyond
the addressable range of your application program.
- 108 (X'6C')
- The VTAM ACB vector list
length byte is incorrectly specified.
- 112 (X'70')
- You attempted to open an ACB that is in the process of being closed.
This can occur when a VTAM application
program job step or subtask is canceled or terminates abnormally.
The process of closing the ACB can continue after the job step or
subtask has actually terminated. Subsequently, if the job step is
restarted or the subtask is reattached before the ACB closing process
has been completed, an OPEN macroinstruction that is then issued for
that ACB fails.
- 114 (X'72')
- This
code occurs when an OPEN ACB fails for an LU 6.2 application with
VERIFY=OPTIONAL or VERIFY=REQUIRED for one of the following reasons:
- The security management product is not installed.
- The security management product is not active.
- The security management product resource class APPCLU is not active.
- The application represented by the ACB is not in the security
management product Started Procedures Table.
- 116 (X'74')
- VTAM rejected the takeover by an
alternate application because the original application did not enable
persistence, although it is capable of persistence.
- 118 (X'76')
- OPEN
failed because the specified application is in a recovery pending
state and PERSIST=YES is not specified on the ACB that is being opened.
The OPEN may also fail if the application is in pending terminate
state and an active CDRSC with the same name has been found in the
sysplex.
- 120 (X'78')
- ACB
option mismatch between original application and opening takeover
or recovery application. One or more of the following can apply:
- MACRF mismatch—both values must be either LOGON or NLOGON; they
cannot differ.
- NQNAMES mismatch—both applications must be specified as NQNAMES=YES
or NQNAMES=NO; they cannot differ.
- PERSIST mismatch—both applications must be specified as PERSIST=YES.
- FDX mismatch—both applications must be specified as FDX=YES or
FDX=NO; they cannot differ.
- ISTVAC81 mismatch—the application capabilities vector provided
by the recovering application does not match that of the original
application.
- 140 (X'8C')
- PERFMON=YES is coded on the ACB but the application is not CNM
and POA authorized.
- 188 (X'BC')
- The ACB is in the process of being opened or closed by another
request.
- 244 (X'F4')
- The
application program is not authorized for SRBEXIT=YES. A request to
open an ACB whose corresponding APPL definition statement specifies
SRBEXIT=YES is rejected unless the application program is APF authorized,
or using key 0–7, or in supervisor state.
- 246 (X'F6')
- NIB storage address not valid. A CNM authorized application program
either failed to supply an NIB pointer in the NIB field of the ACB,
or the NIB address supplied lies beyond the addressable range of the
application program.
- 250 (X'FA')
- NIB options not valid. Either an application program without CNM
authorization (specified in its associated VTAM resource definition) supplied an NIB pointer
in its ACB; or, if CNM authorized, the application program failed
to supply valid NIB options on the NIB macroinstruction.
- 254 (X'FE')
- Duplicate unsolicited RU routing requested. The CNM routing table
indicated that this application program was to receive the same unsolicited
formatted requests that were already being routed to another active
CNM authorized application program. Only one application program can
be actively receiving a particular type of RU (for example, RECFMS)
at a time.
- VTAM release level
- Indicates
the address of VTAM release-level
vector. See z/OS Communications Server: SNA Programming for more information about the format of
this vector.
- password
- Specifies
a pointer to a null-terminated string. The application program should
specify NULL if no password is to be supplied. If a password is specified
on PRTCT operand of the APPL definition statement, MIBConnect fails
unless a matching password is provided in the password parameter.
Password protection is to prevent a program from running as a predefined
application program without authorization.
The value of the password
is specified on the PRTCT operand of the APPL definition statement.
The value must conform to the rules for coding this operand described
in the z/OS Communications Server: SNA Resource Definition
Reference. The maximum length is 8 bytes. Valid passwords
contain only alphanumeric characters.
If application program's
ACB name is TOPOMGR, the APPL definition statement with a password
is similar to the following example: TOPOMGR APPL ACBNAME=TOPOMGR,PRTCT=password
Note: The
value of this parameter is converted to uppercase before being passed
to OPEN ACB. This is because VTAM converts
the related definition to uppercase but does not convert OPEN ACB
parameters to uppercase. Without the conversion to uppercase by MIBConnect,
this function would fail if the application provided a lowercase value
for this parameter.
- data space vector length
- If
using data space storage, specify a value that is at least the size
of (ISTRIV10_t), which is the length of the data space vector. If
you are using common storage area storage, specify 0. For an explanation
of these types of storage, see Common storage area storage or data space storage?.
- data space vector
- If
you are using data space storage, specify the address of the data
space vector (ISTRIV10_t). If you are using the CSA interface, specify
NULL. If the MIBConnect function is successful, the fields in this
control block are set by VTAM.
The format of the data space vector is: - Offset
- Meaning
- 0 (X'00')
- Vector Length
- 1 (X'01')
- Vector identifier = X'10'
- 2 (X'02')
- Name of data space. (The field is 8 bytes long.)
- 10 (X'0A')
- Address of interface control block (ISTNMICB)
- 14 (X'0E')
- STOKEN for data space interface. This value is used in ALESERV MVS™ macro to obtain the ALET value.
- 22 (X'16')
- Reserved
- 26 (X'1A')
- Address of the dequeue routine
- 30 (X'1E')
- Address of the release routine
The ISTNMICB structure is allocated in the
data space. The user application must copy this structure into private
storage for any future references because the data space can be deleted
at any time if VTAM is terminated.
Referring to the original after the data space has been deleted results
in an abend. By contrast, calling the dequeue and release routines
using private copies of their addresses causes an error indication
to be returned. It is not valid to refer directly to the data space
through a means other than the dequeue or release routine. Those routines
should not be called after VTAM is
terminated or after issuing the MBDisconnect function.
The
format of the interface control block (ISTNMICB) is: - Offset
- Meaning
- 0 (X'00')
- Reserved
- 4 (X'04')
- Address of the dequeue routine
- 8 (X'08')
- Address of the release routine
- local identifier length
- Indicates
the size of the local identifiers for this application program. The
range is 1—8.
- connection options
- Specify
one of the following values:
- NO_CONNECT_OPTIONS
- Indicates that the application program is to use default behaviors
for the connection with CMIP services.
- SHORT_NAMES
- Indicates that CMIP services is to send distinguished names to
the application program in the short form. Otherwise, CMIP services
sends distinguished names to the application program in the long form.
In either case, the application program can format distinguished names
in strings sent through the API functions in either short or long
form.
For a description of short and long names, see What form of distinguished name?.
Return codes - 0
- The MIBConnect function was successful, but warning messages might
have been issued. Check the OPEN ACB error value parameter for warning
messages.
- MB_ERR_ALLOC
- An error occurred allocating storage. If MB_ERR_ALLOC is received
by the application program from an API function and there is a corresponding
REQS record in the VIT with a nonzero return code, the LPBUF pool
is not large enough and should be increased.
- MB_ERR_CMIP_SERVICES_INACTIVE
- CMIP services is inactive.
If using common storage area storage,
the read queue exit routine stops functioning.
If using data
space storage, messages are not put on the data space.
- MB_ERR_CONNECT
- The MIBConnect was not successful. If the error condition indicated
by the OPEN ACB error value parameter can be eliminated, another MIBConnect
can be issued.
- MB_ERR_INVALID_DS_VECTOR
- The value specified for the data space vector length parameter
is valid, but the data space vector parameter is not provided.
- MB_ERR_INVALID_API_LEVEL
- An incorrect value for the API level parameter was passed.
- MB_ERR_INVALID_APPL_NAME
- The value specified for the application name parameter is longer
than 8 characters.
- MB_ERR_INVALID_CONNECT_OPTIONS
- The value specified on the connection options parameter is not
valid. Specify either NO_CONNECT_OPTIONS or SHORT_NAMES as the value
for the connection options parameter.
- MB_ERR_INVALID_DS_VECTOR_SIZE
- If the data space vector parameter is specified, the data space
vector length must be at least the size of (ISTRIV10_t), which is
the length of the data space vector.
- MB_ERR_INVALID_ENVIRONMENT
- Data space storage was specified on the data space vector length
parameter, but the environment does not support data spaces.
- MB_ERR_INVALID_ERROR_FLAG
- The OPEN ACB error value parameter does not point to a valid storage
location.
- MB_ERR_INVALID_LINK_ID
- The value specified on the link identifier parameter does not
refer to a valid connection.
- MB_ERR_INVALID_LOCAL_ID_SIZE
- The value specified on the local identifier length parameter is
outside the acceptable range of 1—8.
- MB_ERR_INVALID_MAX_INVOKE_IDS
- The value specified for the maximum outstanding requests parameter
is not valid.
- MB_ERR_INVALID_PASSWORD
- The value specified for the password parameter is not between
0 and 8 characters.
- MB_ERR_INVALID_READ_QUEUE_EXIT
- The read queue exit routine was not provided.
- MB_ERR_INVALID_RELEASE_LEVEL
- The value specified for the VTAM release
level parameter is not valid.
- MB_ERR_INVALID_SMAE_NAME
- The value specified for the SMAE name buffer parameter is not
valid.
- MB_ERR_INVALID_SMAE_NAME_SIZE
- The buffer sent to the MIBConnect function is too small to accommodate
the name of the SMAE. The actual amount of storage required is returned
in the SMAE name length parameter.
- MB_ERR_INVALID_SYSTEM_NAME
- The value specified for the system object name buffer parameter
is not valid.
- MB_ERR_INVALID_SYSTEM_NAME_SIZE
- The buffer sent to the MIBConnect function is too small to accommodate
the name of the system object. The actual amount of storage required
is returned in the system object name buffer size parameter.
- MB_ERR_INVALID_TPEND_EXIT
- The TPEND exit routine is not valid.
- MB_ERR_INVALID_USER_DATA
- The user data parameter was not provided.
- MB_ERR_VTAM_INACTIVE
- VTAM is inactive.
Example of function in an application program The
following example shows how the MIBConnect function can be coded in
an application program. typedef struct ReadQueueExitData_tag
{
int ECB;
int ReasonCode;
char Buffer ??(16384??);
} ReadQueueExitData_t;
typedef void *LocalId_t;
char SMAE ??(100??);
char SystemObject ??(100??);
char *VTAM_Release;
const char *ApplName;
const char *Password;
int LinkId;
int rc;
ReadQueueExitData_t ReadQueueExitData;
size_t SMAE_Size, SystemObjectSize;
unsigned int ACB_Info;
extern void ACYCMS2A(void);
extern void ACYCMS6A(void);
rc = APIs.MIBConnect(0, /* always zero for this release */
&LinkId, /* MIBConnect will fill in LinkId
with a handle to the
connection. */
65536, /* maximum number of outstanding
requests */
ApplName, /* ACB name */
(void *)ACYCMS6A, /* TPEND exit */
(void *)ACYCMS2A, /* address of the Read
Queue Exit */
&SMAE_Size, /* On input, this is the size of
the SMAE buffer. On output,
this is the length of the SMAE
name. */
SMAE, /* This is where MIBConnect will
store the SMAE name (if there
is enough room). */
&SystemObjectSize,/* On input, this is the
size of the System Object name
buffer. On output, this is the
length of the System Object
name. */
SystemObject, /* This is where MIBConnect will
store the System Object name
(if there is enough room). */
(int)&ReadQueueExitData, /* This will be provided
to this application's read
queue exit by CMIP Services. */
&ACB_Info, /* If an error occurs opening the
ACB, this will contain the
OPEN ACB error code. */
&VTAM_Release, /* MIBConnect will store the
address of the VTAM release
level here. */
Password, /* ACB password */
0, /* dataspace not used */
NULL, /* dataspace not used */
sizeof(LocalId_t), /* size of local ids
for all objects registered by
this application */
0); /* no special options specified */
|
z/OS Communications Server: CMIP Services and Topology Agent Guide
Copyright IBM Corporation 1990, 2014