NetLink Package for TCL

Current Version 2.6
For security reasons, this package is not openly available. The NetLink support group will determine if a project requires access to the NetLink server. After such access is granted, this package can be obtained from the author.

Author: Evan Rempel erempel@UVic.CA

NetLink::Wait token

Takes as an argument the token returned by NetLink::Password, NetLink::StatusID or NetLink::RDBQuery. Wait for the transaction associated with token to complete. Return the status of the token connection.

NetLink::Discard token

Takes as an argument the token returned by NetLink::Password, NetLink::StatusID or NetLink::RDBQuery. This frees up the memory reserved for the asynchronous call. If this is not done, a memory leak will result.

NetLink::Data token

Takes as an argument the token returned by NetLink::Password, NetLink::StatusID or NetLink::RDBQuery.

Return the current Data received/translated in the token data stream. This routine is unreliable until NetLink::Status is Non-Empty. The appropriate method is to use a -command option that signifies completion, or not use the -command option which will cause the Password, StatusID, RDBQuery and StatusSetup to wait for completion prior to returning contol to the calling application.

NetLink::Status token

Takes as an argument the token returned by NetLink::Password, NetLink::StatusID or NetLink::RDBQuery.

Return the status of the data stream associated with token. Values are:

ok

data stream was received correctly, however, there may be received data that indicates a remote error occured.

eof

the data stream was terminated prior to all of the data being received.

timeout

the NetLink Server did not respond within the timout period

connectwait

the NetLink Server did not establish a TCP/IP connection within the -connectwait specified

NetLink::Backup count

Switch to the backup NetLink Server for the next "count" calls. If count is 0, switch to the primary server immediately.

The Backup NetLink Server is only used by the routines

• NetLink::Password
• NetLink::StatusSetup
• NetLink::StatusID

This has no affect when using the -token flag with the StatusID routine. In this case, the StatusSetup would have to be used to create a new connection to the backup server. This would be counted as 1 call.

Typically, one would switch to the backup server after receiving any one of the following responses from Status routine: eof, timeout, connectwait.

Return 1

NetLink::Password NetLinkID password options

Verify the NetLinkID password pair.

Returns a token that can be used with

• NetLink::Status
• NetLink::Data
• NetLink::Wait
• NetLink::Discard

NetLink::Data will return one of the following

Yes

The name/password pair is valid and the name is currently an active netlink ID.

No

The name/password is not valid.

Deleted

The name is a deleted NetLinkID. No attempt was made to validate the password

Locked

The name is a locked NetLinkID. No attempt was made to validate the password

Expired

The name is a expired NetLinkID. No attempt was made to validate the password

Not Authorized

The host on which the NetLink::Password routine was run is not authorized to use the NetLink server.

absent

any code not covered above

options A group of optional pairs with the following elements

-command cmdName

If present, the NetLink::Password routine will not wait for the completion of receiving to take place, but returns immediately with the NetLink token. Upon completion of the receiving, whether errors have occured or not, cmdName is called with the NetLink token.

cmdName Token

-connectwait milliseconds

If present, will abort the NetLink Password verification attempt if a socket connection to the NetLink Server can not be established within the milliseconds.

-timeout milliseconds.

If present, will abort the NetLink Password verification attempt if the NetLink Server has not responed with an answer within the milliseconds.

NetLink::StatusSetup options

This can be used to establish a channel that can be used with the StatusID routine. This is unnecesary if only a few StatusID calls are to be made, but can be substancially faster for large call sets. this routine can take upto 60 seconds to complete under normal circumstances, so be sure to allow a large -timeout option.

Returns a token that can be used with

• NetLink::Status
• NetLink::Data
• NetLink::StatusID
• NetLink::Wait
• NetLink::Discard

If NetLink::Status is "ok" then NetLink::Data will return an array with the following values:

ReturnStr

• Unknown - Unexpected failure
• Ok - Success
• Error - Batch setup could not be completed

Message

The message that the NetLink server has returned. This will be most useful when the ReturnStr is Unknown or Error.

options A group of optional pairs with the following elements

-command cmdName

If present, the NetLink::Password routine will not wait for the completion of receiving to take place, but returns immediately with the NetLink token. Upon completion of the receiving, whether errors have occured or not, cmdName is called with the NetLink token.

cmdName Token

-connectwait milliseconds

If present, will abort the NetLink Password verification attempt if a socket connection to the NetLink Server can not be established within the milliseconds.

-timeout milliseconds.

If present, will abort the NetLink Password verification attempt if the NetLink Server has not responed with an answer within the milliseconds.

NetLink::StatusID NetLinkID options

Obtain the current status of a NetLink ID.

Returns a token that can be used with

• NetLink::Status
• NetLink::Data
• NetLink::StatusID (if -token is used)
• NetLink::Wait
• NetLink::Discard

If NetLink::Status is "ok" then NetLink::Data will return an array with the following values:

ReturnStr

• Unknown - unexpected failure
• Yes - Success
• NonExistant - NetLink ID does not exist
• Invalid - An invalid character was in the NetLinkID
• Absent - anything other than the above

Type

• Student - netlink ID is a student account
• Employee - netlink ID is an employee account
• Department - netlink ID is a departmental account
• Secondary - netlink ID is a secondary account
• Temporary - netlink ID is a temporary account

Number

Only valid for "Type" Student or Employee. Either the student or employee number.
See Type above.

DeptCode

Only valid for "Type" Department or Secondary. The department code that the NetLink ID is associated with.
See Type above.

Owner

Only valid for "Type" of Temporary. The NetLink ID that owns the temporary ID.
See Type above.

Status

a list of status flags.

• active - Valid and usable NetLink ID
• locked - a locked NetLinkID
• expired - an expired NetLinkID

options A group of optional pairs with the following elements

-command cmdName

If present, the NetLink::Password routine will not wait for the completion of receiving to take place, but returns immediately with the NetLink token. Upon completion of the receiving, whether errors have occured or not, cmdName is called with the NetLink token.

cmdName Token

-connectwait milliseconds

If present, will abort the NetLink Password verification attempt if a socket connection to the NetLink Server can not be established within the milliseconds.

-timeout milliseconds.

If present, will abort the NetLink Password verification attempt if the NetLink Server has not responed with an answer within the milliseconds.

-token token

The token from NetLink::StatusSetup This will cause the StatusID routine to reuse the connection that was established with StatusSetup, resulting in much faster operation and only one tcp/ip socket being used.

NetLink::RDBQuerySetup options

This can be used to establish a channel that can be used with the RDBQuery routine. This is unnecesary if only a few RDBQuery calls are to be made, but can be substancially faster for large call sets. this routine can take upto 60 seconds to complete under normal circumstances, so be sure to allow a large -timeout option.

Returns a token that can be used with

• NetLink::Status
• NetLink::Data
• NetLink::RDBQuery
• NetLink::Wait
• NetLink::Discard

If NetLink::Status is "ok" then NetLink::Data will return an array with the following values:

ReturnStr

• Yes - Success
• Error - Batch setup could not be completed

options A group of optional pairs with the following elements

-command cmdName

If present, the NetLink::RDBQuery routine will not wait for the completion of receiving to take place, but returns immediately with the NetLink token. Upon completion of the receiving, whether errors have occured or not, cmdName is called with the NetLink token.

cmdName Token

-connectwait milliseconds

If present, will abort the RDBQuery verification attempt if a socket connection to the RDBQuery Server can not be established within the milliseconds.

-timeout milliseconds.

If present, will abort the RDBQuery verification attempt if the RDBQuery Server has not responed with an answer within the milliseconds.

NetLink::RDBQuery type number options

Obtain information about the UVic member.

Input

• type - any one of
  • S - indicates that number will be a student number.
  • E - indicates that number will be an employee number.
  • H - indicates that the request is a historgram on the student number.
  • A - appointment list. Number will be an employee.
• Number - the student or employee number

Returns a token that can be used with

• NetLink::Status
• NetLink::Data
• NetLink::Wait
• NetLink::Discard

If NetLink::Status is "ok" then NetLink::Data will return:

Type A Request

An array with the following fields

number

employee number

status

ACE for active appointments RDBQuery values of ACE ACF ACG ACA RET

dept

list of department codes for those departments that the user is considered active in.

All other requests

A string of the following format:

Return string when type is S or E has format:

• 1 - 1 #RUTYPE (A1)
• 2 - 2 #SPACE1 (A1)
• 3 - 11 #RUNUMBER (A9)
• 12 - 12 #SPACE2 (A1)
• 13 - 15 #RSTATUS (A3)
• 14 - 14 #SPACE3 (A1)
• 15 - 22 #RBIRTHDATE (A8)
• 23 - 23 #SPACE4 (A1)
• 24 - 43 #RSURNAME (A20)
• 44 - 44 #SPACE5 (A1)
• 45 - 85 #RFORNAMES (A40)
• 86 - 86 #SPACE6 (A1)
• 87 - 107 #RPREFNAME (A20

Current values for #RSTATUS are:

• FMT - Invalid request format.
• CMD - Request Code was not 'E' or 'S'
• ERR - Request caused a program check, don't do that one again.
• UNK - No record found for the specified individual.

for employees:

• ACA - Active associate faculty.
• ACE - Active employee.
• ACF - Active faculty.
• ACG - Active, grant funded.
• NAC - not active.
• LEV - Employee on leave.
• KWT - Employee has been terminated or quit.

For students,

• NRG - Not registered.
• RGG - Registered graduate.
• RGU - Registered undergraduate.
• RGX - Registered extension student.

Return string for H has format

• 1 - 1 #RUTYPE (A1)
• 2 - 2 #SPACE1 (A1)
• 3 - 11 #RUNUMBER (A9)
• 12 - 12 #SPACE2 (A1)
• 13 - 21 #RDEPARTMENT (A9)
• for each course registered in
  • #SPACE (A1)
  • #RCRSNAME (A3)
  • #SPACE (A1)
  • #RNUMCREDIT (A4)

options A group of optional pairs with the following elements

-command cmdName

If present, the NetLink::Password routine will not wait for the completion of receiving to take place, but returns immediately with the NetLink token. Upon completion of the receiving, whether errors have occured or not, cmdName is called with the NetLink token.

cmdName Token

-connectwait milliseconds

If present, will abort the NetLink Password verification attempt if a socket connection to the NetLink Server can not be established within the milliseconds.

-timeout milliseconds.

If present, will abort the NetLink Password verification attempt if the NetLink Server has not responed with an answer within the milliseconds.

-token token

The token from NetLink::RDBQuerySetup This will cause the RDBQuery routine to reuse the connection that was established with RDBQuerySetup, resulting in much faster operation and only one tcp/ip socket being used.

Revision History

Version 2.6 - July 25, 2000

• Added the ability to handle the LVF and LVS for faculty and staff on leave respectively.

Version 2.5 - May 29, 2000

• Added the ability to reuse RDBQuery connections.
• Added the translation of the RDBQuery A operation

Version 2.4 - May 12, 2000

• Fixed race condition for finishing and closing sockets and timers

Version 2.3 - May 04, 2000

• The NetLink::Discard routine did not cancel outstanding timers or fileevents allowing for orphaned events and timers. This routine now cancels all of these items.

Version 2.2 - Apr 21, 2000

• First release