Infrastructure Control Functions

infCtl Reporting and Control Function
HowTo

The infCtl (infrastructure control) tool is used to interactively interrogate internal process information or alter process control information and flags while the process is running. In order to support this activity call-back functions must be written to provide application specific controls and information.

for the new function to be recognized, you must build a table of prompts and call-back functions using the CTL_BGN, CTL_CB( "PROMPT", func ), and CTL_END, then register the table before infInit() is called, using the CTL_REG macro. In the CTL_CB( "Prompt", func ) "Prompt" is what is printed on the menu and the func is the call-back to associate with the menu prompt. The first uppercase letter of the prompt is the selection character (if Prompt = "aFat", 'F' is the selection character). If your process had something to do with automobiles, you could use the following call-back registration: CTL_CB( "Auto", ctlAuto ) When the letter 'A' is entered at the menu prompt, the function ctlAuto in your process will be called.

The prompt may create a sub-menu by using the form: "main>sub". The "main" part must be selected with it's 1^st uppercase letter then a new menu will be displayed showing all sub-prompts which have the same "main" part. For instance if your process had something to do with color processing you might use these two call-back declarations:
     CTL_CB( "Color>Red", ctlRed )
     CTL_CB( "Color>Blue", ctlBlue )
to produce a top level menu selection of "Color" with two entries in it's sub-menu of "Red" and "Blue".

The prototype of the call-back is:
Number One, function requests info and expects an answer:
int ctlAuto( char *msg, char *ans )
{ // CTLPROCESS WHICH ASKS A QUESTION AND EXPECTS AN ANSWER
     if( ans )
     { // SECOND CALL, WITH REQUESTED ANSWER
          DebugFlag = atoi( ans ); // EXPECTING A NUMERIC ANSWER
          return( OK ); // PRINT PROCESS' MAIN MENU
     }
     // FIRST CALL, PRINT INFO WHICH ASKS A QUERSION
     fmtCat( msg, "\"Enter a value for the Debug Flag\"" );
     return( NOTFND ); // DON'T PRINT PROCESS' MENU (EXPECT RESPONSE)
}

Number 2, information printing only function:
int ctlEverything( char *msg, char *ans )
{ // CTLPROCESS WHICH ONLY DISPLAYS INFORMATION
     fmtCat( msg, "\"" );
     fmtCat( msg, "%d kinds of information\n", infoCount );
     fmtCat( msg, "\"" );
     return( OK ); // PRINT PROCESS' MAIN MENU
}

Note the return code for number 1, above is "NOTFND" if the upper function is to remain at the current menu level and "OK" to back up (reprint previous) menu level. Also note that posted information MUST be enclosed in double quotes (") Please see the infrastructure docs under the str (string processing) module/layer for a description of fmtCat().
The maximum size of any ctl message is CTLMAX or 10,000 bytes, so be careful not to try to display too much. If you need vast amounts of information, use the trace layer and enable it dynamically.

Under the covers stuff: the ctl system uses low level IO and event type (message) EVTCLTQ and EVTCLTA for query and answer respectively. The messages passed between infCtl and the process is ascii text and the process' control function MUST ONLY APPEND TO THIS MESSAGE. Some examples:
Query To Process Format:
"hostname" main menu request.
"hostname>Io" Io Sub-menu request (list Io sub-funcs)
"hostname>ctlLevel>subLevel:1234" Value "1234" returned from prompt request "hostname>ctlLevel:HowNowBrownCow" String returned from prompt request
Response To infCtl Format: InfCtl always waits for and returns ":response" (Note COLON). "hostname>[Trc,Io,Cfg]" Main Menu with read single char \"A Report\"hostname>Io[PortActivity,Stats]" print Rpt, Menu, get rsp "hostname>Trc>Lvl\"Please Enter new trace level\" "hostname>Cfg\"Do you want to proceed (Y/N)\"" print Rpt, get rsp. Menu is enclosed in square brackets "[]". Report enclosed in DblQuotes \"Report\" Menus get single char response, all others require string resp terminated by NEWLINE or SPACE.

A brief interaction might look like:

root->infCtl -v mcu	INITIAL COMMAND
"mcu"
mcu[Kill,iD,Io,Trc,Msg,Cfg,Procs]"	RESPONSE, MAIN MENU, FROM SYSGO (mcu)
mcu[Kill,iD,Io,Trc,Msg,Cfg,Procs,Quit] I	INFCTL DISPLAYS, USER ENTERS 'I' (I/O)
"mcu>Io"	INFCTL SENDS TO SYSGO (mcu)
mcu>Io[Ports,Addrs,Cnts,aLrm,Evt]"	SYSGO RESPONDS TO INFCTL WITH I/O MENU
mcu>Io [Ports,Addrs,Cnts,aLrm,Evt,Quit] E	INFCTL DISPLAYS I/O MENU, USER ENTERS 'e'
mcu>Io>Evt"

mcu>Io"Event#	Hits	Registered@	SYSGO RESPONDS WITH IO>EVENT REPORT
2	1	msg.c	616
3	0	io1.c	481
7	3	sys.c	227
10	16	ctl.c	31
11	4	sys.c	226
13	1	trc.c	212
17	11	io1.c	482
18	11	sys.c	223
19	1	io1.c	483

"[Ports,Addrs,Cnts,aLrm,Evt]" SYSGO APPENDS IO MENU

Event	# Hits	Registered@	INFCTL DISPLAYS IO>EVENT REPORT
2	1	msg.c	616
3	0	io1.c	481
7	3	sys.c	227
10	16	ctl.c	31
11	4	sys.c	226
13	1	trc.c	212
17	11	io1.c	482
18	11	sys.c	223
19	1	io1.c	483

mcu>Io [Ports,Addrs,Cnts,aLrm,Evt,Quit] INFCTL DISPLAYS IO MENU