FA~Link Set Up Host Servers_20030512

FA~Link

For Bookstores

Setting Up Host Servers

Prepared by

Trimdata Staff

April 2002 Revised January 2003

Note: This document is best viewed in MS WORD.

Setting Up Host Servers 1 of 15

January 2003 Copyright © 2002, 2003, Trimdata Corp

Table of Contents

This Document contains the following Chapters:

FA~Link Communications Overview 1. Defining FLNK Host Server (PHSD)

A Step by Step Guide for setting up the Host Servers.

2. Starting Up the Host Servers (PHSP or PHNM) A Step by Step Guide for starting and shutting down the Host Servers.

3. Monitoring the Host Servers (PHSM) A Step by Step Guide for reviewing the status of all Host Servers.

4. Resetting Host Servers after Improper Shutdown (PHSR) A Step by Step Guide for resetting improperly shutdown Host Servers.

5. Testing Socket Communications

Set by Step guide for testing the communications between Host Servers and Transaction Sources



FLNK Communications Overview Primary communication and the transfer of data in FA~Link for Bookstores occur between the “Transaction Source” in the Bookstore and the “Host Server” within Colleague. The Host Server is a software program. It resides within the FLNK application and controls data flow and processing between the bookstore’s Transaction Source and the Colleague processing.

Figure 1: Typical Host Server, Transaction Source Environment

The Host Server monitors a port (socket) through which it receives and sends data from the Bookstore Point of Sale (POS) System. The “Transaction Source” is now optional. Whether it is present at your installation will depend strictly upon which POS system is in use in your campus store. If there is not a “Transaction Source”, then each cash register connects directly to a single port (socket) on the Colleague machine, which is monitored by the FA~Link Host Server process. The only real difference in the two configurations is that the port monitored by the Host Server will communicate with only a single external port when there is a Transaction Source, but will communicate with multiple external ports, one for each cash register, when there is not a Transaction Source. With either setup, the Host Server validates incoming data in various ways, accesses the financial resources processing within FA~Link and Colleague, and returns a response to the Cash Register (via the Transaction Source if there is one).

Colleague

Student

Files

FA~Link

Interface

Trans- action

Source

Host Server

Cash Register

Cash Register

Bookstore

POS

Cash Register



Chapter 1: DEFINING HOST SERVERS A Host Server is a “Definition” containing a set of specific information relating to the Colleague end of the communications link. The server definition(s) are created and maintained by the FLNK Host Server Definition screen (PHSD). The definitions are kept in the FLNK.HOST.SERVERS file. The Fields of the FLNK Host Server Definition Screen with typical values are shown in Figure 2.

-------------------------------------------------------------------------------- | 01/31/03 14:16 FA~LINK HOST SRVR DEFINITION PHSD | | | | FLNK HS.ID................: HOST1 | | | |------------------------------------------------------------------------------| | | | 1 Server Description........: Host Server #1 | | 2 Socket Number.............: 2001 | | 3 Number Connections Allowed: 10 | | 4 Server Trxlog Level.......: 9 | | | | | | | | | | | | | | | | | | | | | | | |------------------------------------------------------------------------------|

FIGURE 2: FA~LINK Host Server Definition (PHSD) Screen FLNK Server ID The FLNK Server ID is the key to a Host Server. It should have some logic to it, e.g., BK1, BK2, OPSSVR, TESTSVR. These Server Ids are created and maintained by the FLNK Host Server Definition Screen (PHSD). [They should also be documented in the Unix “/etc/services” file.]

cd /etc ex services Host1 2001/tcp # Bookstore FLNK Host Server #1 Host2 2002/tcp # Bookstore FLNK Host Server #2 Host3 2003/tcp # Bookstore FLNK Host Server #3 Host4 2004/tcp # Bookstore FLNK Host Server #4

1 FLNK Server Description The purpose or special nature of the Server Definition is further expanded in the Description field. 2 FLNK Socket Number The Socket Number is the unix socket number used by the Host Server for communications connection to the Transaction Source or Cash Register. Socket



numbers are created and maintained at the Unix level by the unix system administrator, and must be sockets that are not used for anything else on the unix system. A different socket number is used for each Host Server. 3 FLNK Number Connections Allowed The maximum number of connections allowed for the specified socket (port). If a Transaction Source is used (see above), then this should be set to 1. Otherwise it should be set to the number of cash registers that will be used. If this field is left blank, the maximum number of registers will be used as the default for the maximum number of connections allowed. 4 FLNK TRXLOG (Transaction Logging) Level The Host Server incorporates a transaction logging capability that can be set at various levels of sensitivity. Based on this setting, various error and operations messages are recorded in FLNK.TRXLOG file. This file is used for analyzing special situations that may arise. The logging Categories and Levels are as follows: Errors 0 -- Fatal errors, e.g., unable to open file 1 -- Posting errors 2 -- Validation errors, e.g., bad student id 3 -- Communications Packet input error, e.g., formatting 4 -- Warnings, e.g., change of Cashier code Processing 5 -- Communications, establishment of communications link 6 -- Establishment of a "conversation" for the exchange of data 7 -- Posting activities 8 -- Validation procedures 9 -- Miscellaneous processing Typically, the level would be set at one of the error levels, with 2 and 4 being common settings. The processing levels are typically used only when problems are being encountered. They provide a means of tracing the actual program flow to determine when, where, and why a given problem is being encountered.



Chapter 2: STARTING/STOPPING A HOST SERVER The sequence of initiating communications between the campus store POS and Colleague is important. There are currently two Host Server routines for FA~Link, but only one should be installed on your system. Your Host Server may be known as either PHSP or PHNM. Please refer to the documentation for your POS system for instructions on starting up a Transaction Source or a Cash Register. With a Transaction Source Starting Up: Host Server, Transaction Source Stopping: Transaction Source, Host Servers (happens automatically) The Host Server is started with the FLNK Host Server Processor (PHSP or PHNM) Screen. An example is in Figure 3.

-------------------------------------------------------------------------------- | 01/31/03 14:43 FLNK HOST SERVER B7 PHNM | | | | | |------------------------------------------------------------------------------| | FLNK Server ID.............: HOST1 | | FLNK Server Description....: Host Server #1 | | FLNK Socket Number.........: 2001 | | Max Connections this socket: 1 | | FLNK TRXLOG Level..........: 9 | | | | | | | | | | | | | | | | | | | | | | | | | |------------------------------------------------------------------------------|

Figure 3: FLNK Host Server Startup/Processing (PHSP or PHNM) Screen

Enter the Host Server ID. Its definition is displayed for visually verifying that the proper Host Server was selected. <FINISH> will start the Host Server and set its status to “Listening”. The Transaction Source is then started (See Chapter 5). When the two servers have completed the electronic connection, the Host Server’s status is then set to “Conversation”. When the Transaction Source is shut down, the Host Server is automatically shut down and its status returned to “Inactive”.



When the PHSP or PHNM Screen is first opened, it performs a validity check of the Category AR Code Taxing attribute and the Sales Tax Setup. (See ‘Setting Up for Bookstore Purchases’ Document for details.) Any errors are displayed and the screen cancels. Without a Transaction Source Your POS system may not include a Transaction Source, which means simply that each cash register connects directly to the Host Server port. The Host Server must be started before any Cash Register can successfully connect. The Host Server is started with the FLNK Host Server Processor (PHSP or PHNM) Screen. An example is in Figure 4.

-------------------------------------------------------------------------------- | 01/31/03 14:43 FLNK HOST SERVER B7 PHNM | | | | | |------------------------------------------------------------------------------| | FLNK Server ID.............: HOST1 | | FLNK Server Description....: Host Server #1 | | FLNK Socket Number.........: 2001 | | Max Connections this socket: 10 | | FLNK TRXLOG Level..........: 9 | | | | | | | | | | | | | | | | | | | | | | | | | |------------------------------------------------------------------------------|

Figure 4: FLNK Host Server Startup/Processing (PHSP or PHNM) Screen

Cash Registers may connect, disconnect, and reconnect at will. But when there is only one Cash Register that remains connected, the Host Server shuts down automatically when that Cash Register disconnects. If the Host Server is shut down, it remains shut down until it is restarted using PHSP or PHNM.



Chapter 3: MONITORING HOST SERVERS (PHSM) A Host Server will have one of three statuses. - ”Inactive” is the status when the Host Server is initially created and whenever it

has been properly shut down. It is ready to be restarted at any time. - “Listening” is the status when it has been started but has not yet connected to the

Transaction Source. - “Conversation” is when the Host Server and Transaction Source or Cash Register

have established a communications link and are capable of passing data to one another.

The current status of each server can be seen by using the FLNK Host Server Monitor (PHSM) Inquiry Screen. An example appears in Figure 5. This screen shows all Host Servers that have been defined. There will normally be only one Host Server “Listening” or in “Conversation”.

Figure 5: The Host Server Monitor Screen (PHSM)



The FLNK Server Status Detail Screen The FLNK Server Status Detail Screen shows a short history of the selected server’s activity in reverse chronological order with the current status at the top of the window. This is an Inquiry Screen. Figure 6 shows the Detail Screen with typical data. Note the repeating sets of INACTIVE, LISTENING, CONVERSATION status.

Figure 6: PHSM Detail Screen



Chapter 4: FLNK HOST SERVER RESET (PHSR) There are three statuses for a server, as are shown on the FLNK Host Server Monitor (PHSM) screen:

INACTIVE indicates that the server is not currently being used and is available for startup.

LISTENING indicates that the host server is started and is waiting for a bookstore Transaction Source or Cash Register to ‘call’ and complete the communications link.

CONVERSATION indicates that the communications link is established and that data is being (or can be) transmitted between the Host and the POS System.

When the communications link is properly closed as described in Chapter 2, the server status is reset to INACTIVE. When selecting a Host Server on the PHSP or PHNM screen for startup, if the current status of the selected server definition is not ‘INACTIVE’, the following message appears: “Server xxx is already running”. Either you did not realize that the selected server is already running or a prior communications link had been improperly terminated, e.g., a power failure, which left the status incorrectly set. Regardless of the cause, the proper response is <CANCEL>. If the condition is the result of an improper shutdown, the FLNK Host Server Reset (PHSR) Screen can be used to reset the Server Definition. An example is seen in Figure 7. Note well the message displayed in the middle of the PHSR Screen.

Figure 7: FLNK Host Server Reset Screen (PHSR)



Enter the Host Server ID, visually verify that the proper Host Server was selected, and respond “Yes”. The status will be reset to “Inactive” allowing the Host Server to be started using the PHSP or PHNM Screen. Some improper terminations cause the Host Server to continue running. In this case, contact your Colleague System Administrator, who can terminate the Host Server so it can be properly restarted. This usually also requires a reset using PHSR.



Chapter 5: TESTING SOCKET COMMUNICATIONS This Chapter contains a series of 3 tests that will verify the correct operation of the socket interface functions and the TCP/IP network. This section is information for system administrators. The tests occur in several stages: 1. Ping Test 2. Socket Send Test 3. Socket Test Each test is independent but serial in nature. If a given test fails, all subsequent tests will also fail. Similarly, if a given test passes, all earlier tests would have also passed. Therefore, to quickly verify the operation, initially run Test 3 (Socket Test). If it fails, then start with Test 1 and work down until all problems are resolved. Test 1: Ping Test Each FLNK register and (if a separate computer) Transaction Source may act as a TCP/IP host. You should be able to ‘ping’ from any TCP/IP host to any other host. The file server does not provide a ping function; you can ping to it but not from it. TCP/IP addresses (###.###.###.###) are used in the examples below. If aliases have been established, they can be used instead. [You will need to know what directory the “ping” command is in. If unsure, use the “find” command.

find /usr -name "ping" -print /usr/sbin/ping

You can either change to that directory to run the ping tests or include the full path when you issue the command, e.g., /usr/sbin/ping 199.78.43.5. When the ping command is successfully executed, it will execute repeatedly displaying a message as it does so. A CTRL-C stops the command. It will then give a summary.

cd /usr/sbin ping 199.78.43.5 PING 199.78.43.5: 64 byte packets 64 bytes from 199.78.43.5: icmp_seq=0. time=18. ms 64 bytes from 199.78.43.5: icmp_seq=1. time=5. ms 64 bytes from 199.78.43.5: icmp_seq=2. time=4. ms 64 bytes from 199.78.43.5: icmp_seq=3. time=4. ms 64 bytes from 199.78.43.5: icmp_seq=4. time=5. ms 64 bytes from 199.78.43.5: icmp_seq=5. time=4. ms CTRL-C ----199.78.43.5 PING Statistics---- 6 packets transmitted, 6 packets received, 0% packet loss round-trip (ms) min/avg/max = 4/6/18



If the ping command cannot successfully execute, it will appear to do nothing. Execute CTRL-C to obtain a summary.

ping 199.78.43.9 PING 199.78.43.9: 64 byte packets CTRL-C ----199.78.43.9 PING Statistics---- 36 packets transmitted, 0 packets received, 100% packet loss

If you are attempting to use an alias that is not properly set up, you will receive an error message.

/usr/sbin/ping hacl-hb /usr/sbin/ping: unknown host hacl-hb

If the physical network is operating properly, you should be able to ping from your Unix machine to each of the Transaction Sources or Cash Registers in the bookstore. Test 2: Socket Send Test (Socket Functions) This function is becoming obsolete and may not be on your system. This test uses the socket functions in the form of a test program without involving either Unidata or the Unidata runtime machine. It demonstrates that the socket functions are able to establish a connection and send data from the host platform. The test uses telnet on a Bookstore FLNK host as the test responder. ( ) From the Colleague host, run the ‘socket send’ test utility. It will initialize the

socket environment and wait for a connection.

> cd /datatel/release/COLL16/FLNK/SOCKET.INTFC > flnk.skt.send

( ) From a Bookstore FLNK host, run telnet to request a connection. (The Novell

implementation of telnet is ‘tnvt220’.) The ‘send test’ utility will accept the connection, send a message to be displayed by telnet, close down the connection, and terminate. You should see a message from the ‘send test’ utility on the telnet display. The ‘send test’ utility on the Bookstore FLNK host should then terminate.

Login to the Novell file server as ‘ts’ (‘ts1 or ‘ts2’ as appropriate). Exit to DOS

tnvt220 coll 2001 The details of this will vary for other networks.

Test 3 Socket Test



This function is becoming obsolete and may not be on your system. This test establishes a connection between the Colleague host and the Bookstore Transaction Source. If this connectivity is working, then bringing registers on-line will normally work with little or no additional setup. This test uses the same Unibasic socket functions as the main host server program. The test responder in this case is the POS Transaction Source. Colleague applications and the FLNK registers are not involved. This test presumes that at least one Colleague Host Server Id is defined. It also assumes that a configuration record with at least one session was established for the Bookstore Transaction Source. The critical parameters are

• the TCP/IP address in dot notation of the Colleague host • the socket listen port is the same as in the Colleague host server ID • passwords are null.

From the Colleague host in Unidata, run the FLNK.SKT.TEST program and enter the Host server ID to be used for this test. The program runs in stages. After the first and second stages, it prompts ‘Is this what you want?’ Respond with ‘Y’ to continue or ‘END’ to abort the test.

>udt :FLNK.SKT.TEST STARTING FLNK.SKT.TEST <Enter> to continue <ENTER> ENTER SERVER PARMS ID OR END: HOST1

( ) Display of Server Definition. <ENTER> to continue.

Server parameters for: HOST1 Description.........: Host Server 1 Individual ids......: Logging detail......: 4 Applications........: BOOKSTORE Socket listen port..: 2001 Conv req logon id...: Server Status.......: INACTIVE Server Dates........: 11265 Server Times........: 68455 <Enter> to continue <ENTER>

( ) Echo test. If the echo test appears OK, respond ‘Y’ to start the ‘open conversation’ test. Testing SKECHO function SKECHO CCTO=arg for echo test CCFROM=SKECHO input was:arg for echo test Ready to proceed to open conversation test IS THIS WHAT YOU WANT? ([NL], N, END):y



( ) ‘Open Conversation’ test. When the test reaches the ‘waiting’ point, start the

Bookstore Transaction Source. If this test seems OK, respond ‘Y’ to proceed to the ‘close conversation’ test.

Testing open conversation loc= reg= rcpt= rcv.pkt= SKT.PROLOG . . Getting Ready to Establish Communications loc= reg= rcpt= rcv.pkt= SKT.PROLOG . . Listening on Socket 2001 Start up the Transaction Source from the TS Workstation loc= reg= rcpt= rcv.pkt= SKT.CONNECT . . Waiting ...

Start Bookstore Transaction Source

loc= reg= rcpt= rcv.pkt= SKWCON . . Socket Packet Accepted loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt=00000000000000000000*001 00*0000000000*0000000000*0000000000*0000000000*00032%%%% SKT.RECEIVE . . Packet Received loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt= ACK.OPEN.CONV . . Conversation Opened loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt= SKT.SEND . . Response Packet Sent Open Conversation was ok; would normally start Transactions

Ready to proceed to close conversation test IS THIS WHAT YOU WANT? ([NL], N, END): Y

( ) ‘Close Conversation’ test. When prompted by the test program, close down the

conversation from the Bookstore Transaction Source. Both the Colleague host test program and the Transaction Source should terminate at this point.

Testing close conversation

Shut down the Transaction Source now from the TS workstation loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt=00000000000000000000*001 01*0000000000*0000000000*0000000000*0000000000*00032%%%% SKT.RECEIVE . . Packet Received loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt= SKT.SEND . . Response Packet Sent Closing down the socket interface loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt= SKT.DISCONNECT . . Disconnected from Socket 2001 loc=0000000000 reg=0000000000 rcpt=0000000000 rcv.pkt= SKT.EPILOG . . Done Listening on Socket 2001 Comm Test complete for HOST1

If everything appears OK at this point, all parts of the socket interface are properly installed. These tests are for communications only, and the FA~Link for Bookstores processing is not directly tested. There are many issues and parameters that affect the actual data processing. However, the on-line communications interface is isolated from application processing issues by these tests as much as possible.



When working with the application, if the registers go on-line but get incorrect results, then the FLNK interface software is probably installed and working OK and further application testing is in order. If one or more registers won’t go on-line, then the above tests must be selectively used to isolate the communication problem(s).

FA~Link Set Up Host Servers_20030512

Documents

Transcript of FA~Link Set Up Host Servers_20030512