ELowell: /* Program */

2015-09-30T20:37:51Z

Program

← Older revision		Revision as of 20:37, 30 September 2015
Line 203:		Line 203:
	===Program===		===Program===
	<p class="code">PROCEDURE SERVER		<p class="code">PROCEDURE SERVER
	BEGIN		BEGIN<nowiki>
	<nowiki>
	******************************************************************		******************************************************************
	* S A M P L E H O R I Z O N S E R V E R P R O G R A M *		* S A M P L E H O R I Z O N S E R V E R P R O G R A M *
Line 225:		Line 224:
	* DATA AND SUBROUTINES *		* DATA AND SUBROUTINES *
	******************************************		******************************************

	%CID IS STRING LEN 8		%CID IS STRING LEN 8
	%RECVMSG IS STRING LEN 255		%RECVMSG IS STRING LEN 255
Line 249:		Line 247:

	RECEIVE_LOOP:		RECEIVE_LOOP:

	RECEIVE %RECVMSG FROM %CID RESULT %RESULT		RECEIVE %RECVMSG FROM %CID RESULT %RESULT

Line 262:		Line 259:

	* FALL THROUGH WHEN ADVICE=1 (RECEIVED DATA) *		* FALL THROUGH WHEN ADVICE=1 (RECEIVED DATA) *

	AUDIT 'RECEIVED FROM PARTNER:' AND %RECVMSG		AUDIT 'RECEIVED FROM PARTNER:' AND %RECVMSG

Line 268:		Line 264:

	SEND:		SEND:

	SEND 'HELLO, SAILOR!' TO %CID REQSEND %REQSEND		SEND 'HELLO, SAILOR!' TO %CID REQSEND %REQSEND

Line 277:		Line 272:

	* FALL THROUGH WHEN ADVICE=1 (SEND SUCCEEDED) *		* FALL THROUGH WHEN ADVICE=1 (SEND SUCCEEDED) *

	JUMP TO RECEIVE_LOOP		JUMP TO RECEIVE_LOOP

Line 285:		Line 279:

	HANDLE_CONFIRM:		HANDLE_CONFIRM:

	AUDIT '* PARTNER REQUESTED CONFIRMATION *'		AUDIT '* PARTNER REQUESTED CONFIRMATION *'

Line 297:		Line 290:

	* FALL THROUGH IF ADVICE = 1 (SEND ERROR SUCCEEDED) *		* FALL THROUGH IF ADVICE = 1 (SEND ERROR SUCCEEDED) *

	CLOSE PROCESS %CID		CLOSE PROCESS %CID

	*** IF CLOSE FAILS, JUST GIVE UP		*** IF CLOSE FAILS, JUST GIVE UP

	CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)		CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
	JUMP TO (END, -		JUMP TO (END, -
Line 308:		Line 299:

	HANDLE_SIGNAL:		HANDLE_SIGNAL:

	AUDIT '* PARTNER SENT SIGNAL - CLOSING CONVERSATION *'		AUDIT '* PARTNER SENT SIGNAL - CLOSING CONVERSATION *'

	CLOSE PROCESS %CID		CLOSE PROCESS %CID

	*** IF CLOSE FAILS, JUST GIVE UP		*** IF CLOSE FAILS, JUST GIVE UP

	CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)		CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
	JUMP TO (END, -		JUMP TO (END, -
Line 321:		Line 309:

	HANDLE_ERROR:		HANDLE_ERROR:

	AUDIT '* PARTNER SENT ERROR - CLOSING CONVERSATION *'		AUDIT '* PARTNER SENT ERROR - CLOSING CONVERSATION *'

	CLOSE PROCESS %CID		CLOSE PROCESS %CID

	*** IF CLOSE FAILS, JUST GIVE UP		*** IF CLOSE FAILS, JUST GIVE UP

	CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)		CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
	JUMP TO (END, -		JUMP TO (END, -
Line 334:		Line 319:

	HANDLE_CLOSE:		HANDLE_CLOSE:

	AUDIT '* PARTNER CLOSED CONVERSATION *'		AUDIT '* PARTNER CLOSED CONVERSATION *'

	CLOSE PROCESS %CID		CLOSE PROCESS %CID

	*** IF CLOSE FAILS, JUST GIVE UP		*** IF CLOSE FAILS, JUST GIVE UP

	CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)		CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
	JUMP TO (END, -		JUMP TO (END, -
Line 347:		Line 329:

	BOGUS:		BOGUS:

	AUDIT '* STAT_CHECK RETURNED AN UNDEFINED ADVICE CODE *'		AUDIT '* STAT_CHECK RETURNED AN UNDEFINED ADVICE CODE *'
	JUMP TO END		JUMP TO END

	ABORT:		ABORT:

	AUDIT '* STAT_CHECK ADVISES THAT WE ABORT *'		AUDIT '* STAT_CHECK ADVISES THAT WE ABORT *'
	JUMP TO END		JUMP TO END

	END:		END:

	*** ALWAYS SET THE APSY COMMUNICATION VARIABLE BEFORE LEAVING		*** ALWAYS SET THE APSY COMMUNICATION VARIABLE BEFORE LEAVING

ELowell: Created page with "==Overview== This topic presents sample Horizon User Language (SOUL) client and server programs, a subroutine to check Horizon return codes, and an example of remote file upda..."

2015-09-30T19:58:26Z

Created page with "==Overview== This topic presents sample Horizon User Language (SOUL) client and server programs, a subroutine to check Horizon return codes, and an example of remote file upda..."

New page

==Overview==
This topic presents sample Horizon User Language (SOUL) client and server programs, a subroutine to check Horizon return codes, and an example of remote file updating.
==Client Program==

The following example is a small client program that establishes a conversation with a partner process, sends a message to the partner, receives messages from the partner, and ends the conversation.

The STAT_CHECK subroutine is used after each HORIZON statement to determine the appropriate subsequent action for the program to take. Subroutine STAT_CHECK is found in [[#Subroutine to check Horizon return codes|Subroutine to check Horizon return codes]]. 

The HORIZON LINK, PROCESSGROUP, and PROCESS definition commands are included as comments at the beginning of the procedure, for convenient reference.

===Companion program===

[[#Server sample|Server sample]] has an example of a server program that can communicate with the client program shown here.

===Program===
PROCEDURE CLIENT
BEGIN
<nowiki>
******************************************************************
*** S A M P L E H O R I Z O N C L I E N T P R O G R A M ***
******************************************************************
*****************************************
*** NETWORK DEFINITIONS ***
*****************************************
*
* DEFINE LINK VIRGINIA WITH SCOPE=SYSTEM LOCALID=FREDBURG -
* INBUFSIZE=2048 TRANSPORT=VTAM PROTOCOL=LU62 SESSIONS=4
*
* DEFINE PROCESSGROUP BOULDER WITH SCOPE=SYSTEM OUTLIMIT=4 -
* INLIMIT=0 REMOTEID=COLORADO LINK=VIRGINIA
*
* DEFINE PROCESS WEEKEND WITH SCOPE=SYSTEM PARTNER=SOMEFUN -
* DESTINATION=(BOULDER,FAC,MOAB,ARCHES) DATALEN=500
*
******************************************
*** DATA AND SUBROUTINES ***
******************************************

%CID IS STRING LEN 8
%RECVMSG IS STRING LEN 255
%RESULT IS STRING LEN 15
%REQSEND IS FLOAT
%ADVICE IS FLOAT

%CID = 'MADAME'

INCLUDE STAT_CHECK

***************************************
*** MAIN PROGRAM ***
***************************************

OPEN PROCESS WEEKEND CID %CID AT FAC

CALL STAT_CHECK (%CID, %HRZN_OPEN, %RESULT, %REQSEND, %ADVICE)
JUMP TO (ABORT) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (OPEN SUCCEEDED) ***

SEND 'HELLO, MADAME!' TO %CID REQSEND %REQSEND

CALL STAT_CHECK (%CID, %HRZN_SEND, %RESULT, %REQSEND, %ADVICE)
JUMP TO (ABORT, -
HANDLE_ERROR, -
HANDLE_SIGNAL) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (SEND SUCCEEDED) ***

RECEIVE_LOOP:

RECEIVE %RECVMSG FROM %CID RESULT %RESULT

CALL STAT_CHECK (%CID, %HRZN_RECEIVE, %RESULT, %REQSEND, -
%ADVICE)
JUMP TO (ABORT, -
HANDLE_ERROR,-
BOGUS, -
SEND, -
HANDLE_CLOSE, -
HANDLE_CONFIRM) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (RECEIVED DATA) ***

PRINT 'RECEIVED FROM PARTNER:' AND %RECVMSG

JUMP TO RECEIVE_LOOP

SEND:

SEND 'GOODBYE, MADAME!' TO %CID REQSEND %REQSEND

CALL STAT_CHECK (%CID, %HRZN_SEND, %RESULT, %REQSEND, %ADVICE)
JUMP TO (ABORT, -
HANDLE_ERROR, -
HANDLE_SIGNAL) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (SEND SUCCEEDED) ***

CLOSE PROCESS %CID

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
JUMP TO (END, -
ABORT, -
HANDLE_ERROR) %ADVICE

**************************************************
*** EXCEPTION HANDLERS ***
**************************************************

HANDLE_CONFIRM:

PRINT '*** PARTNER REQUESTED CONFIRMATION ***'

SEND ERROR TO %CID REQSEND %REQSEND

CALL STAT_CHECK(%CID, %HRZN_SEND_ERROR, %RESULT, %REQSEND, -
%ADVICE)
JUMP TO (ABORT, -
BOGUS, -
ABORT) %ADVICE - 1

*** FALL THROUGH IF ADVICE = 1 (SEND ERROR SUCCEEDED) ***

CLOSE PROCESS %CID

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)

*** IF CLOSE FAILED, JUST GIVE UP

JUMP TO (END, -
END, -
END) %ADVICE

HANDLE_SIGNAL:

PRINT '*** PARTNER SENT SIGNAL - CLOSING CONVERSATION ***'

CLOSE PROCESS %CID

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)

*** IF CLOSE FAILED, JUST GIVE UP

JUMP TO (END, -
END, -
END) %ADVICE

HANDLE_ERROR:

PRINT '*** PARTNER SENT ERROR - CLOSING CONVERSATION ***'

CLOSE PROCESS %CID

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)

*** IF CLOSE FAILED, JUST GIVE UP

JUMP TO (END, -
END, -
END) %ADVICE

HANDLE_CLOSE:

PRINT '*** PARTNER CLOSED CONVERSATION ***'

CLOSE PROCESS %CID

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)

*** IF CLOSE FAILED, JUST GIVE UP

JUMP TO (END, -
END, -
END) %ADVICE

BOGUS:

PRINT '*** STAT_CHECK RETURNED AN UNDEFINED ADVICE CODE ***'
JUMP TO END

ABORT:

PRINT '*** STAT_CHECK ADVISES THAT WE ABORT ***'
JUMP TO END

END: END
END PROCEDURE </nowiki>

==Server Sample==

The following example is a server program that receives messages from a partner program and sends back a message to the partner, repeating this sequence until the partner ends the conversation.

The STAT_CHECK subroutine is used after each HORIZON statement to determine the appropriate subsequent action for the program to take. Subroutine STAT_CHECK is found in [[#Subroutine to check Horizon return codes|Subroutine to check Horizon return codes]].

The HORIZON LINK, PROCESSGROUP, and PROCESS definition commands are included as comments at the beginning of the procedure for convenient reference.

In this example, the server program is invoked using the Remote Procedure Invocation (RPI) subsystem. See [[Horizon SOUL interface#Application testing with the RPI subsystem|Application testing with the RPI subsystem]].

===Companion program===

[[#Client program|Client program]] has an example of a client program that can communicate with the server program shown here.

===Program===
PROCEDURE SERVER
BEGIN
<nowiki>
******************************************************************
*** S A M P L E H O R I Z O N S E R V E R P R O G R A M ***
******************************************************************
******************************************
*** NETWORK DEFINITIONS ***
******************************************
*
* DEFINE LINK BOULDER WITH SCOPE=SYSTEM LOCALID=COLORADO -
* INBUFSIZE=2048 TRANSPORT=VTAM PROTOCOL=LU62 SESSIONS=4
*
* DEFINE PROCESSGROUP VIRGINIA WITH SCOPE=SYSTEM OUTLIMIT=0 -
* INLIMIT=4 REMOTEID=FREDBURG LINK=BOULDER LOGIN=NOTRUST -
* GUESTUSER=REJECT
*
* DEFINE PROCESS SOMEFUN WITH SCOPE=SYSTEM SUBSYSTEM=RPI -
* FROM=(VIRGINIA) DATALEN=500 SUBSYSPARM='MYFILE SERVER OPEN'
*
******************************************
*** DATA AND SUBROUTINES ***
******************************************

%CID IS STRING LEN 8
%RECVMSG IS STRING LEN 255
%RESULT IS STRING LEN 15
%REQSEND IS FLOAT
%ADVICE IS FLOAT

%CID = 'SAILOR'

INCLUDE STAT_CHECK

******************************************
*** MAIN PROGRAM ***
******************************************
OPEN PROCESS SOMEFUN CID %CID ACCEPT

CALL STAT_CHECK (%CID, %HRZN_OPEN, %RESULT, %REQSEND, %ADVICE)
JUMP TO (ABORT) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (OPEN SUCCEEDED) ***

AUDIT 'CONVERSATION HAS BEGUN'

RECEIVE_LOOP:

RECEIVE %RECVMSG FROM %CID RESULT %RESULT

CALL STAT_CHECK (%CID, %HRZN_RECEIVE, %RESULT, %REQSEND, -
%ADVICE)
JUMP TO (ABORT, -
HANDLE_ERROR, -
BOGUS, -
SEND, -
HANDLE_CLOSE, -
HANDLE_CONFIRM) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (RECEIVED DATA) ***

AUDIT 'RECEIVED FROM PARTNER:' AND %RECVMSG

JUMP TO RECEIVE_LOOP

SEND:

SEND 'HELLO, SAILOR!' TO %CID REQSEND %REQSEND

CALL STAT_CHECK (%CID, %HRZN_SEND, %RESULT, %REQSEND, %ADVICE)
JUMP TO (ABORT, -
HANDLE_ERROR, -
HANDLE_SIGNAL) %ADVICE - 1

*** FALL THROUGH WHEN ADVICE=1 (SEND SUCCEEDED) ***

JUMP TO RECEIVE_LOOP

******************************************
*** EXCEPTION HANDLERS ***
******************************************

HANDLE_CONFIRM:

AUDIT '*** PARTNER REQUESTED CONFIRMATION ***'

SEND ERROR TO %CID REQSEND %REQSEND

CALL STAT_CHECK(%CID, %HRZN_SEND_ERROR, %RESULT, %REQSEND, -
%ADVICE)
JUMP TO (ABORT, -
BOGUS, -
ABORT) %ADVICE - 1

*** FALL THROUGH IF ADVICE = 1 (SEND ERROR SUCCEEDED) ***

CLOSE PROCESS %CID

*** IF CLOSE FAILS, JUST GIVE UP

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
JUMP TO (END, -
END, -
END) %ADVICE

HANDLE_SIGNAL:

AUDIT '*** PARTNER SENT SIGNAL - CLOSING CONVERSATION ***'

CLOSE PROCESS %CID

*** IF CLOSE FAILS, JUST GIVE UP

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
JUMP TO (END, -
END, -
END) %ADVICE

HANDLE_ERROR:

AUDIT '*** PARTNER SENT ERROR - CLOSING CONVERSATION ***'

CLOSE PROCESS %CID

*** IF CLOSE FAILS, JUST GIVE UP

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
JUMP TO (END, -
END, -
END) %ADVICE

HANDLE_CLOSE:

AUDIT '*** PARTNER CLOSED CONVERSATION ***'

CLOSE PROCESS %CID

*** IF CLOSE FAILS, JUST GIVE UP

CALL STAT_CHECK (%CID, %HRZN_CLOSE, %RESULT, %REQSEND, %ADVICE)
JUMP TO (END, -
END, -
END) %ADVICE

BOGUS:

AUDIT '*** STAT_CHECK RETURNED AN UNDEFINED ADVICE CODE ***'
JUMP TO END

ABORT:

AUDIT '*** STAT_CHECK ADVISES THAT WE ABORT ***'
JUMP TO END

END:

*** ALWAYS SET THE APSY COMMUNICATION VARIABLE BEFORE LEAVING

%X = $SETG('COMM','EXIT')
END
END PROCEDURE </nowiki> 

==Subroutine to Check Horizon Return Codes==

The following subroutine can be used in Horizon User Language (SOUL) programs to simplify the checking of the status information that is set by each HORIZON statement. The subroutine condenses the large number of combinations of $STATUS codes, RESULT codes, and so on into a small set of recommended actions for the program: 
<ul>
<li>Continue normally.</li>
<li>Terminate immediately.</li>
<li>Respond to partner's SEND ERROR.</li>
<li>Respond to partner's SIGNAL PROCESS.</li>
<li>Start to SEND.</li>
<li>Partner has closed conversation.</li>
<li>Respond to partner's CONFIRM. </li>
<li>No more data expected. </li>
<li>Expected data has not arrived. </li>
</ul>

Refer to the [[#Client program|client]] and [[#Server progrma|server]] program samples for illustrations of how the subroutine is to be used.

===Subroutine===
PROCEDURE STAT_CHECK <nowiki>*************************************************************************

SUBROUTINE STAT_CHECK ( %PROCESS IS STRING LEN 10 INPUT -
%STATEMENT IS FLOAT INPUT, -
%RESULT IS STRING LEN 15 INPUT, -
%REQSEND IS FLOAT INPUT, -
%ADVICE IS FLOAT OUTPUT )

**********************************************************************
* STAT_CHECK SHOULD BE CALLED AFTER EACH HORIZON STATEMENT. *
* IT EVALUATES THE RELEVANT STATUS INFORMATION THAT WAS SET BY *
* THE STATEMENT AND RETURNS A RECOMMENDED PROGRAM-ACTION CODE. *
* *
* %PROCESS -- THE CONVERSATION ID (CID) OF THE PROCESS *
* %STATEMENT-- THE HORIZON STATEMENT JUST ISSUED *
* 1 = OPEN (O) 8 = SEND (S) *
* 2 = CONFIRM (CF) 9 = SEND ERROR (SE) *
* 3 = CONFIRMED (CFD) 10 = SIGNAL (SP) *
* 4 = CLOSE (C) 11 = INVITE (I) *
* 5 = FLUSH (F) 12 = TEST (T) *
* 6 = QUERY (Q) 13 = WAIT (W) *
* 7 = RECEIVE (R) *
* %RESULT -- THE RESULT VARIABLE FROM THE 'RECEIVE' STATEMENT *
* %REQSEND -- THE REQSEND VARIABLE FROM 'SEND' OR 'SEND ERROR' *
* %ADVICE -- (OUTPUT) THE RECOMMENDED ACTION TO TAKE. USE THE *
* FOLLOWING CHART TO DETERMINE WHICH ADVICE CODES *
* STAT_CHECK CAN RETURN FOR DIFFERENT HORIZON *
* STATEMENTS: *
* *
* - - - S T A T E M E N T S - - - - - A D V I C E C O D E S - - *
* *
* O CF CFD C F I Q R S SE SP T W *
* X X X X X X X X X X X X X 1 - CONTINUE *
* X X X X X X X X X X X X X 2 - ABORT *
* - X - X - X - X X - - - - 3 - GOT 'SEND ERROR' *
* - X - - - - - - X X - - - 4 - GOT 'SIGNAL PROCESS' *
* - - X - - - - X - - - - - 5 - TRANSITION TO 'SEND' *
* - - X - - X - X - - - - - 6 - PARTNER CLOSED CONVERSATION *
* - - - - - - - X - - - - - 7 - TRANSITION TO 'CONFIRM' *
* - - - - - - - - - - - X X 8 - NO OUTSTANDING INVITES *
* - - - - - - - - - - - X - 9 - NO RECEIPTS YET *
**********************************************************************

%STATUS = $STATUS
%STATUSD = $STATUSD

JUMP TO (O,CF,CFD,C,F,Q,R,S,SE,SP,I,T,W) %STATEMENT

X: **********************************
* INVALID STATEMENT CODE *
**********************************

JUMP TO ABORT

O: **********************************
* OPEN PROCESS *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSE
JUMP TO ABORT
END IF

CF: **********************************
* CONFIRM *
**********************************

*** FIRST SEE IF SIGNAL RECEIVED FROM PARTNER

IF %REQSEND = 1 THEN
JUMP TO REQUEST_TO_SEND
ELSEIF %STATUS = 0 THEN
JUMP TO CONTINUE

*** CHECK FOR 2/2 (PARTNER RESPONDED TO CONFIRM WITH SEND ERROR)

ELSEIF %STATUS = 2 AND %STATUSD = 2 THEN
JUMP TO SEND_ERROR
ELSE
JUMP TO ABORT
END IF

CFD: **********************************
* CONFIRMED *
**********************************

%S IS STRING LEN 8

IF %STATUS = 0 THEN

*** SEE WHAT THE CONVERSATION STATE HAS CHANGED TO

QUERY PROCESS %PROCESS STATE %S
IF %S = 'CLOSE' THEN
JUMP TO CLOSE_BY_REMOTE
ELSEIF %S = 'SEND' THEN
JUMP TO SEND
ELSE
JUMP TO CONTINUE
END IF

ELSE
JUMP TO ABORT
END IF

C: **********************************
* CLOSE PROCESS *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE

*** CHECK FOR 2/2 (PARTNER RESPONDED TO CONFIRM WITH SEND ERROR)

ELSEIF %STATUS = 2 AND %STATUSD = 2 THEN
JUMP TO SEND_ERROR
ELSE
JUMP TO ABORT
END IF

F: **********************************
* FLUSH PROCESS *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSE
JUMP TO ABORT
END IF

Q: **********************************
* QUERY PROCESS *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSE
JUMP TO ABORT
END IF

R: **********************************
* RECEIVE *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSEIF %STATUS = 1 THEN

*** ANALYZE THE RESULT VARIABLE FOR APPROPRIATE ACTION

*** DATA TRUNCATED OR INCOMPLETE - ASSUME THIS ISN'T DESIRABLE

IF %RESULT = 'DATA TRUNCATED' THEN
JUMP TO ABORT
ELSEIF %RESULT = 'DATA INCOMPLETE' THEN
JUMP TO ABORT
ELSEIF %RESULT = 'SEND' THEN
JUMP TO SEND

*** ALL FLAVORS OF CONFIRM STATE - TELL USER TO DO 'CONFIRMED'.
*** AFTERWARD, STAT_CHECK WILL SAY 'SEND', 'CLOSE', ETC.

ELSEIF %RESULT = 'CONFIRM' THEN
JUMP TO CONFIRM
ELSEIF %RESULT = 'CONFIRM SEND' THEN
JUMP TO CONFIRM
ELSEIF %RESULT = 'CONFIRM CLOSE' THEN
JUMP TO CONFIRM
ELSE
JUMP TO ABORT
END IF

*** CHECK FOR 2/2 (PARTNER RESPONDED TO CONFIRM WITH SEND ERROR)

ELSEIF %STATUS = 2 AND %STATUSD = 2 THEN
JUMP TO SEND_ERROR

*** CHECK FOR 4/0 (INDICATES PARTNER ENDED CONVERSATION NORMALLY)

ELSEIF %STATUS = 4 AND %STATUSD = 0 THEN
JUMP TO CLOSE_BY_REMOTE
ELSE
JUMP TO ABORT
END IF

S: **********************************
* SEND *
**********************************

IF %STATUS = 0 THEN

*** SEE IF SIGNAL RECEIVED FROM PARTNER

IF %REQSEND = 1 THEN
JUMP TO REQUEST_TO_SEND
ELSE
JUMP TO CONTINUE
END IF

*** CHECK FOR 2/2 (PARTNER RESPONDED TO CONFIRM WITH SEND ERROR)

ELSEIF %STATUS = 2 AND %STATUSD = 2 THEN
JUMP TO SEND_ERROR
ELSE
JUMP TO ABORT
END IF

SE: **********************************
* SEND ERROR *
**********************************

*** SEE IF SIGNAL RECEIVED FROM PARTNER

IF %REQSEND = 1 THEN
JUMP TO REQUEST_TO_SEND

*** NO SIGNAL, SO CHECK %STATUS

ELSEIF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSE
JUMP TO ABORT
END IF

SP: **********************************
* SIGNAL PROCESS *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSE
JUMP TO ABORT
END IF

I: **********************************
* INVITE *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSEIF %STATUS = 2 AND %STATUSD = 2 THEN
JUMP TO SEND_ERROR
ELSEIF %STATUS = 4 THEN
IF %STATUSD = 0 THEN
JUMP TO CLOSE_BY_REMOTE
ELSE
JUMP TO ABORT
END IF
ELSE
JUMP TO ABORT
END IF

T: **********************************
* TEST FOR RECEIPT *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSEIF %STATUS = 1 THEN
IF %STATUSD = 1 THEN
JUMP TO NEVER_MORE
ELSEIF %STATUSD = 2 THEN
JUMP TO NOT_YET
ELSE
JUMP TO ABORT
END IF
ELSE
JUMP TO ABORT
END IF

W: **********************************
* WAIT FOR RECEIPT *
**********************************

IF %STATUS = 0 THEN
JUMP TO CONTINUE
ELSEIF %STATUS = 1 THEN
IF %STATUSD = 2 THEN
JUMP TO NEVER_MORE
END IF
END IF
JUMP TO ABORT

******************************************************************
*** SET THE ADVICE CODE AND EXIT. ***
******************************************************************
CONTINUE:
%ADVICE = 1
JUMP TO EXIT

ABORT:
%ADVICE = 2
JUMP TO EXIT

SEND_ERROR:
%ADVICE = 3
JUMP TO EXIT

REQUEST_TO_SEND:
%ADVICE = 4
JUMP TO EXIT

SEND:
%ADVICE = 5
JUMP TO EXIT

CLOSE_BY_REMOTE:
%ADVICE = 6
JUMP TO EXIT

CONFIRM:
%ADVICE = 7
JUMP TO EXIT

NEVER_MORE:
%ADVICE = 8
JUMP TO EXIT

NOT_YET:
%ADVICE = 9
JUMP TO EXIT

******************************************************************
*** SUBROUTINE EXIT PATH ***
******************************************************************

EXIT:

******************************************************************
*** NOTE: THE FOLLOWING AUDIT LOGIC IS USEFUL AS A DEBUGGING ***
*** TOOL FOR TRACING HORIZON STATEMENTS BUT MAY BE REMOVED ***
*** OR BYPASSED FOR EFFICIENCY IF DESIRED. ***
******************************************************************
*** AUDIT RESULT OF EACH STAT_CHECK INVOCATION ***

%STMT IS STRING LEN 14

IF %STATEMENT = 1 THEN
%STMT = 'OPEN'
ELSEIF %STATEMENT = 2 THEN
%STMT = 'CONFIRM'
ELSEIF %STATEMENT = 3 THEN
%STMT = 'CONFIRMED'
ELSEIF %STATEMENT = 4 THEN
%STMT = 'CLOSE'
ELSEIF %STATEMENT = 5 THEN
%STMT = 'FLUSH'
ELSEIF %STATEMENT = 6 THEN
%STMT = 'QUERY'
ELSEIF %STATEMENT = 7 THEN
%STMT = 'RECEIVE'
ELSEIF %STATEMENT = 8 THEN
%STMT = 'SEND'
ELSEIF %STATEMENT = 9 THEN
%STMT = 'SEND ERROR'
ELSEIF %STATEMENT = 10 THEN
%STMT = 'SIGNAL PROCESS'
ELSEIF %STATEMENT = 11 THEN
%STMT = 'INVITE'
ELSEIF %STATEMENT = 12 THEN
%STMT = 'TEST'
ELSEIF %STATEMENT = 13 THEN
%STMT = 'WAIT'
ELSE
%STMT = '**UNDEFINED**'
END IF

%ADV IS STRING LEN 20

IF %ADVICE = 1 THEN
%ADV = 'CONTINUE'

ELSEIF %ADVICE = 2 THEN
%ADV = 'ABORT'
ELSEIF %ADVICE = 3 THEN
%ADV = 'HANDLE SEND ERROR'
ELSEIF %ADVICE = 4 THEN
%ADV = 'HANDLE SIGNAL'
ELSEIF %ADVICE = 5 THEN
%ADV = 'START SENDING'
ELSEIF %ADVICE = 6 THEN
%ADV = 'PARTNER CLOSED'
ELSEIF %ADVICE = 7 THEN
%ADV = 'HANDLE CONFIRM'
ELSEIF %ADVICE = 8 THEN
%ADV = 'NOTHING ACTIVE'
ELSEIF %ADVICE = 9 THEN
%ADV = 'NOTHING YET'
END IF

QUERY PROCESS %PROCESS STATE %S

%TRACE IS STRING LEN 255
%TRACE = 'STAT_CHECK:' -
WITH ' Statement=' WITH %STMT -
WITH ' %STATUS=' WITH %STATUS WITH '/' WITH %STATUSD

*** AUDIT RESULT VARIABLE AFTER RECEIVE

IF %STATEMENT = 7 THEN
%TRACE = %TRACE WITH ' Result=' WITH %RESULT

*** AUDIT REQSEND VARIABLE AFTER SEND OR SEND ERROR

ELSEIF %STATEMENT = 8 OR %STATEMENT = 9 THEN
%TRACE = %TRACE WITH ' Reqsend=' WITH %REQSEND
END IF

%TRACE = %TRACE -
WITH ' State=' WITH %S -
WITH ' Advice=' WITH %ADVICE WITH '/' WITH %ADV -
WITH ' Cid=' WITH %PROCESS

*** USE 'PRINT' FOR CLIENT PROGRAM, 'AUDIT' FOR SERVER PROGRAM

IF $VIEW('IODEV') EQ '27' THEN
AUDIT %TRACE
ELSE
PRINT %TRACE
END IF
******************************************************************
*** END OF AUDITING ***
******************************************************************

RETURN: RETURN
END SUBROUTINE STAT_CHECK

*******************************************************************
* *
* THE FOLLOWING VARIABLES MAY BE USED AS THE %STATEMENT PARAMETER *
* IN A CALL TO STAT_CHECK, TO MAKE YOUR PROGRAM EASIER TO READ *
* (BE SURE TO EXECUTE THESE ASSIGNMENT STATEMENTS *BEFORE* YOU *
* REFERENCE THE VARIABLES.) *
* *
* EXAMPLE: OPEN PROCESS %CID *
* CALL STAT_CHECK(%CID,%HRZN_OPEN,%RESULT,%REQSEND,%ADVICE) *
* *
*******************************************************************
%HRZN_OPEN = 1
%HRZN_CONFIRM = 2
%HRZN_CONFIRMED = 3
%HRZN_CLOSE = 4
%HRZN_FLUSH = 5
%HRZN_QUERY = 6
%HRZN_RECEIVE = 7
%HRZN_SEND = 8
%HRZN_SEND_ERROR = 9
%HRZN_SIGNAL = 10
%HRZN_INVITE = 11
%HRZN_TEST = 12
%HRZN_WAIT = 13
END PROCEDURE

</nowiki> 

==Remote Updating Example ==

The applications considered thus far have been inquiry-only, but Horizon also permits remote file updating. By definition, remote updating of a local node occurs when data received at the local node during a Horizon conversation is stored at the local node. Horizon accommodates this single node updating using standard Model 204 recovery features.

Coordinated updating and recovery between multiple nodes is not provided with Version 2, Release 2 of Horizon. Multiple-node updating and recovery requires an additional conversation protocol, called two-phase commit, along with corresponding enhancements to the recovery logic of Model 204.

The example (in pseudo code) in [[#Single-node remote update|Single-node remote update]] illustrates how a Horizon single-node remote update can be accomplished using existing Model 204 recovery logic. The arrows in the example indicate when data is physically transmitted across the network. The numbers in parentheses show the order in which the statements in the programs are processed. 

Single node remote update
[[File:Horizon_fig7-1_single_node.gif|468px]] 

The steps shown in parentheses in [[#Single-node remote update|Single-node remote update]] are as follows:
<table>
<tr class="head">
<th>Step</th>
<th>Description</th>
</tr>
<tr>
<td>(1)</td>
<td>Program A sends data to its remote partner.</td>
</tr>
<tr>
<td>(2)</td>
<td>Program A issues a confirmation request. This causes the data and a confirmation indicator to be sent to Program B.</td>
</tr>
<tr>
<td>(3)</td>
<td>Program B receives the data. If the receive fails for any reason, the appropriate cleanup logic is invoked.</td>
</tr>
<tr>
<td>(4)</td>
<td>Program B does a second RECEIVE, and verifies that what it has received is the confirmation request. If the confirmation request is not present, the cleanup logic is called. An update unit is never started.</td>
</tr>
<tr>
<td>(5)</td>
<td>Program B stores the data it receives into its file, and this begins an update unit.</td>
</tr>
<tr>
<td>(6)</td>
<td>Program B acknowledges that it has made the update by issuing a CONFIRMED statement.</td>
</tr>
<tr>
<td>(7)</td>
<td>If Program A is still active, $STATUS from the confirmation is 0, and Program B commits the current update unit. Otherwise, Program B backs the update out.</td>
</tr>
<tr>
<td>(8-9)</td>
<td>When something (a confirmation or an error indication) is received, Program A reports the result to the end user.</td>
</tr>
</table>

===Multiple-node updating===

An application that requires updates at more than one node can be written using the current version of Horizon, provided that it does not depend upon Model 204 recovery alone to assure it of database consistency across network nodes. Such an application can be designed in one of two ways:
<ol>
<li>
The application is designed so that there are no database consistency dependencies across nodes.

In this case, Model 204 recovery protects each individual node. Such a design implies that each node's update is seen by recovery as a separate transaction, disjoint from updates at any other node.</li>

<li>The application is designed so that the application takes responsibility for detecting and correcting cross-node inconsistencies.

Such a recovery scheme can sometimes be designed, but an extensive discussion of the issues involved is beyond the scope of this topic.</li>
</ol>

[[#Double-node update|Double-node update]] shows an application that performs updates at two nodes. The numbers in parentheses show the order in which the statements in the programs are processed.

Double-node update
[[File:Horizon_fig7-2_double_node.gif|468px]] 


The steps shown in parentheses in [[#Double-node update|Double-node update]] are as follows:
<table>
<tr class="head">
<th>Steps</th>
<th>Description</th>
</tr>
<tr>
<td>(1)</td>
<td>Program A stores data into a record, and this begins an update unit.</td>
</tr>
<tr>
<td>(2)</td>
<td>Program A sends a copy of the data to its remote partner.</td>
</tr>
<tr>
<td>(3)</td>
<td>Program A issues a confirmation request. This causes the data and a confirmation indicator to be sent to Program B.</td>
</tr>
<tr>
<td>(4)</td>
<td>Program B receives the data. If the RECEIVE fails for any reason, the appropriate cleanup logic is invoked.</td>
</tr>
<tr>
<td>(5)</td>
<td>Program B stores the data it receives into its file. This begins an update unit.</td>
</tr>
<tr>
<td>(6)</td>
<td>Program B verifies that what it has received is the confirmation request. If the confirmation request is not present, the update unit is backed out and the cleanup logic is called.</td>
</tr>
<tr>
<td>(7)</td>
<td>Program B acknowledges that it has made the update by issuing a CONFIRMED statement.</td>
</tr>
<tr>
<td>(8)</td>
<td>
This step begins when the confirmation is sent. If Program A is still active, $STATUS from the confirmation is 0, and Program B commits the current update unit.</td>
</tr>
<tr>
<td>(9)</td>
<td>When something (a confirmation or an error indication) is received, Program A acts according to what it receives:
<ul>
<li>A confirmation ($STATUS=0) signifies that Program B successfully received the update data and stored its record, and is presently committing the update. Program A can therefore commit its update with the near certainty that its partner's commit will also succeed.</li>
<li>An error ($STATUS0) signifies that, for some reason, the Program B update did not succeed. Program A therefore backs out its update.</li>
</ul>
</td>
</tr>
</table>

===Between-node data consistency===

A database consistency problem can occur if Program A terminates before it gets a chance to make the decision at Step 9, or if Program B terminates before it completes Step 8. The application should be designed to check (perhaps at initialization time or just before performing a given update) that the database at each node "looks correct."

Another alternative is for the initiating node to keep a file to which it logs records of the nodes that have been successfully updated. In the event of a network failure, the data in this log file is used for manually coordinating recovery.

Note: The physical consistency of any Model 204 file is always taken care of by Model 204 recovery, and is not a consideration here. Logical consistency within a single Model 204 system is also provided. The only issue that the application designer needs to worry about is logical consistency of data among the different nodes that the application attempts to update. 

[[Category: Horizon]]

Horizon SOUL sample programs - Revision history

ELowell: /* Program */

ELowell: /* Subroutine to Check Horizon Return Codes */

ELowell: Created page with "==Overview== This topic presents sample Horizon User Language (SOUL) client and server programs, a subroutine to check Horizon return codes, and an example of remote file upda..."