Notification Record

The notification record is used to provide event information. You receive this information by using the GetNextNote call. For more information, see GetNextNote. It is a variant record; the number of fields is dependent on the type of notification. For the Pascal declaration of this record. see Figure 1.

Figure 1. Notification Record (Part 1 of 2)

   NotificationInfoType =
        record
        Connection: ConnectionType;
        Protocol: ProtocolType;
        case NotificationTag: NotificationEnumType of
             BUFFERspaceAVAILABLE:
                 (
                 AmountOfSpaceInBytes: integer
                 );
             CertDataComplete
                 (
                 CertDataPtr: CertDataCmplPtrType;
                 );
             CLEARtextRESUMED   
                 (   
                 Connection: ConnectionType;  
                 );
             CONNECTIONstateCHANGED:
                 (
                 NewState: ConnectionStateType;
                 Reason: CallReturnCodeType
                 );
             DATAdelivered:
                 (
                 BytesDelivered: integer;
                 LastUrgentByte: integer;
                 PushFlag: Boolean
                 );
             EXTERNALinterrupt:
                 (
                 RuptCode: integer
                 );
             FRECEIVEerror:
                 (
                 ReceiveTurnCode: CallReturnCodeType;
                 ReceiveRequestErr: Boolean;
                 );
             FSENDresponse:
                 (
                 SendTurnCode: CallReturnCodeType;
                 SendRequestErr: Boolean;
                 );
             IOinterrupt:
                 (
                 DeviceAddress: integer;
                 UnitStatus: UnsignedByteType;
                 ChannelStatus: UnsignedByteType
                 );
             IUCVinterrupt:
                 (
                 IUCVResponseBuf: IUCVBufferType
                 );
             PINGresponse:
                 (
                 PingTurnCode: CallReturnCodeType;
                 ElapsedTime: TimeStampType
                 );

Figure 2. Notification Record (Part 2 of 2)

             QueryTLSComplete:
                 (
                 QTLSTurnCode: CallReturnCodeType;
                 );
             RAWIPpacketsDELIVERED:
                 (
                 RawIpDataLength: integer;
                 RawIpFullLength: integer;
                 );
             RAWIPspaceAVAILABLE:
                 (
                 RawIpSpaceInBytes: integer;
                 );
             READYforHANDSHAKE:
                 (
                 HSTurnCode: CallReturnCodeType;
                 );
             RESOURCESavailable: ();
             SecureHandshakeComplete:
                 (
                 SecHSCompleteDetail: SecureHSCompleteDetailType;
                 );
             SMSGreceived: ();
             TIMERexpired:
                 (
                 Datum: integer;
                 AssociatedTimer: TimerPointerType
                 );
             UDPdatagramDELIVERED:
                 (
                 DataLength: integer;
                 ForeignSocket: SocketType;
                 FullLength: integer
                 );
             UDPdatagramSPACEavailable: ();
             UDPresourcesAVAILABLE: ();
             URGENTpending:
                 (
                 BytesToRead: integer;
                 UrgentSpan: integer
                 );
             USERdefinedNOTIFICATION:
                 (
                 UserData: UserNotificationDataType
                 );
             end;

Connection

Indicates the client’s connection number to which the notification applies. In the case of USERdefinedNOTIFICATION, this field is as supplied by the user in the AddUserNote call.

Protocol

In the case of USERdefinedNOTIFICATION, this field is as supplied by the user in the AddUserNote call. For all other notifications, this field is reserved.

NotificationTag

Is the type of notification being sent, and a set of fields dependent on the value of the tag. Possible tag values relevant to the TCP/UDP/IP interface and the corresponding fields are:

BUFFERspaceAVAILABLE

Notification given when space becomes available on a connection for which TcpSend previously returned NObufferSPACE. For more information about these procedures, see TcpFSend, TcpSend, and TcpWaitSend.

AmountOfSpaceInBytes: Indicates the minimum number of bytes that the TCP/IP service has available for buffer space for this connection. The actual amount of buffer space might be more than this number.

CertDataComplete

The results of the certificate data request.


CertDataCmplPtrType = @ CertDataCompleteDetailType
CertDataCompleteDetailType =
  packed record
    CDComp: CertDataCompleteHdrType;
    CDData: packed array (. 1..CDDataLen.) of char;
  end;
CertDataCompleteHdrType =
  packed record
    CDRetCode: integer;
    CDRetCnt:  integer;
    CDDataLen: UnsignedHalfwordType;
    CDRes:     UnsignedHalfwordType;
  end;

CDData

Is requested data from the certificate. The format is as follows:


+---------------------------------------------------------+
| Len | Code | CertData .... | Len | Code | CertData..... |
+---------------------------------------------------------+

where:

Len: Is a halfword field that contains the total length of the item (Len+Code+CertData). The total of all of the Len fields in the buffer is returned in CDDataLen.
Code: Is a halfword that contains the certificate field code (600-677).
CertData: Is the certificate data that corresponds to the requested code. Note that a single field could appear multiple times in the returned buffer if more than one "answer" is valid.

CDRetCode

Indicates the return code from the certificate request. Possible values are:

0 - No errors.
4021 - The partner value is not valid.
4023 - The partner certificate is not available.
4024 - The certificate does not contain any values.
4025 - The buffer length passed is too large.
4026 - The returned data will not fit in the provided buffer. Partial data is returned.
4027 - The passed buffer pointer is null.
4028 - The number of certificate fields requested (CDReqNum) is 0.
4029 - The number of certificate fields requested (CDReqNum) is greater than 64.
4030 - The requested certificate field is not found.
4031 - The requested certificate field is not valid.
4032 - Both of these errors exist in the return data: A requested certificate field
is not found and a requested certificate field is not valid.

CDRetCnt

Is the number of certificate fields returned in CDData.

CDDataLen

Is the length of the returned certificate data.

CDRes

Is reserved - will be 0.

Usage Notes

Certificate fields will be placed in the CDData buffer in the order in which they appear in the CertReqCodes input structure.
The CDData buffer will contain as many certificate fields as will fit completely. If a requested certificate field does not fit in the buffer, it will not be returned and subsequent fields in the CertReqCodes input structure will also fail. CDRetCode will indicate that not all of the data will fit in CDData. CDRetCnt will reflect the number of completed requests.
If the requested field cannot be found in the certificate, CDData will contain a Len of 4 along with the requested Code. No data will be returned. CDRetCode will be updated to indicate that one or more fields are not present in the certificate.

CLEARtextRESUMED

Notification given when a Close_Notify command is received on the connection.

Connection: Indicates the connection number which received the Close_notify command.

CONNECTIONstateCHANGED

Indicates that a TCP connection has changed state.

NewState: Indicates the new state for this connection.
Reason: Indicates the reason for the state change. This field is meaningful only if the NewState field has a value of NONEXISTENT.

Note:

The following is the sequence of state notifications for a connection.
- For active open:
  - OPEN
  - RECEIVINGonly or SENDINGonly
  - CONNECTIONclosing
  - NONEXISTENT.
- For passive open:
  - TRYINGtoOPEN
  - OPEN
  - RECEIVINGonly or SENDINGonly
  - CONNECTIONclosing
  - NONEXISTENT.
Your program should be prepared for any intermediate step or steps to be skipped.
The normal TCP connection closing sequence can lead to a connection staying in CONNECTIONclosing state for up to two minutes, corresponding to the TCP state TIME-WAIT.
Possible Reason codes giving the reason for a connection changing to NONEXISTENT are:
- OK (means normal closing)
- UNREACHABLEnetwork
- TIMEOUTopen
- OPENrejected
- REMOTEreset
- WRONGsecORprc
- UNEXPECTEDsyn
- FATALerror
- KILLEDbyCLIENT
- TIMEOUTconnection
- TCPipSHUTDOWN
- DROPPEDbyOPERATOR.

DATAdelivered

Notification given when your buffer (named in an earlier TcpReceive or TcpFReceive request) contains data.

Note: The data delivered should be treated as part of a byte-stream, not as a message. There is no guarantee that the data sent in one TcpSend (or equivalent) call on the foreign host is delivered in a single DATAdelivered notification, even if the PushFlag is set.

BytesDelivered: Indicates the number of bytes of data delivered to you.
LastUrgentByte: Indicates the number of bytes of urgent data remaining, including data just delivered.
PushFlag: TRUE if the last byte of data was received with the push bit set.

EXTERNALinterrupt

Notification given when a simulated external interrupt occurs in your virtual machine. The Connection and Protocol fields are not applicable.

RuptCode: The interrupt type.

FRECEIVEerror

Notification given in place of DATAdelivered when a TcpFReceive that initially returned OK has terminated without delivering data.

ReceiveTurnCode: Specifies the reason the TcpFReceive has failed or was canceled. If ReceiveRequestErr is set to FALSE, ReceiveTurnCode contains the same reason as the Reason field in the CONNECTIONstateCHANGED with NewState set to NONEXISTENT notification for this connection (see 2). ReceiveTurnCode could be OK, if the connection closed normally.
ReceiveRequestErr: If TRUE, the TcpFReceive was rejected during initial processing. If FALSE, the TcpFReceive was initially accepted, but was terminated because of connection closing.

Note: Normally, you do not need to take any action upon receipt of this notification with ReceiveRequestErr set to FALSE, because your program receives a CONNECTIONstateCHANGED notification informing it that the connection has been terminated.

FSENDresponse

Notification given when a TcpFSend request is completed, successfully or unsuccessfully.

SendTurnCode: Indicates the status of the send operation.
SendRequestErr: If TRUE, the TcpFSend was rejected during initial processing or during retry after buffer space became available. If FALSE, the TcpFSend was canceled because of connection closing.

IOinterrupt

Notification given when a simulated I/O interrupt occurs in your virtual machine. The Connection and Protocol fields are not applicable.

DeviceAddress: This address corresponds to the DEVICE statement.
UnitStatus: Specifies the status returned by the device.
ChannelStatus: Specifies the status returned by the channel.

IUCVinterrupt

Notification given when a simulated IUCV interrupt occurs in your virtual machine. The Connection and Protocol fields are not applicable.

IUCVResponseBuf: Contains the information returned from the application.

PINGresponse

Notification given when a PINGresponse is received.

PingTurnCode: Specifies the status of the ping operation.
ElapsedTime: Indicates the time elapsed between the sending of a request and the reception of a response. This time does not include the time spent in the simulated Virtual Machine Communication Facility (VMCF) communication between your program and the TCPIP virtual machine. This field is valid only if PingTurnCode has a value of OK.

QUERYtlsCOMPLETE

Notification given when the SSL server has completed verification of the label passed on the QueryTLS command.

ReturnCode: Indicates the status of the QUERYtlsCOMPLETE operation. READYforHANDSHAKE to read: ‘Any other return code indicates a handshake failure.'

RAWIPpacketsDELIVERED

Notification given when your buffer (indicated in an earlier RawIpReceive request) contains a datagram. Only one datagram is delivered on each notification. Your buffer contains the entire IP header, plus as much of the datagram as fits in your buffer.

RawIpDataLength: Specifies the actual data length delivered to your buffer. If this is less than RawIpFullLength, the datagram was truncated.
RawIpFullLength: Specifies the length of the packet, from the TotalLength field of the IP header.

RAWIPspaceAVAILABLE

When space becomes available after a client does a RawIpSend and receives a NObufferSPACE return code, the client receives this notification to indicate that space is now available.

RawIpSpaceInBytes: Specifies the amount of space available always equals the maximum size IP datagram.

READYforHANDSHAKE

Notification given when a TcpSServer command is issued with a null data buffer. It indicates that the connection is now waiting for a handshake.

ReturnCode: Indicates status of the handshake. A return code of OK indicates that the connection is waiting for a handshake. Any other return code indicates that there was a problem and the handshake cannot be done.

RESOURCESavailable

Notice given when resources needed for a TcpOpen or TcpWaitOpen are available. This notification is sent only if a previous TcpOpen or TcpWaitOpen returned ZEROresources.

SECUREhandshakeCOMPLETE

Notification given when SSL has completed the handshake (either inbound or outbound).


SecureHSCompleteDetailType =
	record
		ReturnCode:		SecureTurnCodeType;
		AlertLevel:		SecureAlertLevelType;
		AlertDescription:	SignedHalfwordType;
	end

ReturnCode

Indicates the status of the handshake.


SecureTurnCodeType = (NOALERT, ALERT, TIMEOUT)

NOALERT: The handshake completed successfully.
ALERT: Problems were encountered during the handshake.
TIMEOUT: The handshake did not complete within the time allotted.

AlertLevel

When the ReturnCode is ALERT, this classifies the level of the alert.

SecureAlertLevelType = ( AlertOK, Warning, Fatal )

AlertDescription

When ReturnCode is ALERT, this field contains the details of the failure. An AlertDescription value in the 4000 range indicates an SSL server error as follows:

4001 - The type is not valid.
4002 - The integer format of the IP address is not valid.
4003 - ValidationBuffer is too long.
4004 - Len is either too big or extends beyond the buffer.
4005 - The maximum number of validation fields has been exceeded.
4006 - The dotted decimal format of the IPv4 address is not valid.
4007 - The dotted decimal format of the IPv6 address is not valid.
4008 - Validation of a host name or fully-qualified domain name failed.
4009 - Validation of an IPv4 or IPv6 address failed.
4010 - Validation failed.

An AlertDescription value in the 40000 range indicates a System SSL error. Subtract 40000 from the AlertDescription value and refer to Messages and codes in z/OS Cryptographic Services System Secure Sockets Layer Programming for details.

SMSGreceived

Notification given when one or more Special Messages (Smsgs) arrive. The GetSmsg call is used to retrieve queued Smsgs. For information on the SMSG command, see z/VM: TCP/IP User's Guide.

TIMERexpired

Notification given when a timer set through SetTimer expires.

Datum: Indicates the data specified when SetTimer was called.
AssociatedTimer: Specifies the address of the timer that expired.

UDPdatagramDELIVERED

Notification given when your buffer, indicated in an earlier UdpNReceive or UdpReceive request, contains a datagram. Your buffer contains the datagram excluding the UDP header.

Note: If UdpReceive was used, your buffer contains the entire datagram excluding the header, with the length indicated by DataLength. If UdpNReceive was used, and DataLength is less than FullLength, your buffer contains a truncated datagram. The reason is that the length of your buffer was too small to contain the entire datagram.

DataLength: Specifies the length of the data delivered to your buffer.
ForeignSocket: Specifies the source of the datagram.
FullLength: Specifies the length of the entire datagram, excluding the UDP header. This field is set only if UdpNReceive was used.

UDPdatagramSPACEavailable

Notification given when buffer space becomes available for a datagram for which UdpSend previously returned NObufferSPACE because of insufficient resources.

UDPresourcesAVAILABLE

Notice given when resources needed for a UdpOpen are available. This notification is sent only if a previous UdpOpen returned UDPzeroRESOURCES.

URGENTpending

Notification given when there is urgent data pending on a TCP connection.

BytesToRead: Indicates the number of incoming bytes not yet delivered to the client.
UrgentSpan: Indicates the number of undelivered bytes to the last known urgent pointer. No urgent data is pending if this is negative.

USERdefinedNOTIFICATION

Notice generated from data passed to AddUserNote by your program.

UserData: A 40-byte field supplied by your program through AddUserNote. The Connection and Protocol fields are also set from the values supplied to AddUserNote.