NL8301935A - DIRECT DOCUMENTATION FACILITY. - Google Patents

Description

a * VO 4811 "1 Direct Documentation Facility ...

Arithmetic systems often include a direct documentation facility, which makes different types of system data available to users in response to giving documentation or "help" commands. For example, a user may give a documentation command, such as HELP TERM = BILLING-IDENTIFIER in response to which the system provides documentation for the user in his or her post regarding the meaning of the term "billing identifier", as used in the system is being used - The user can also give a documentation command, such as HELP COMM & ND = CALL in response, on which the system provides documentation on how to use the "call" command. Another possibility is a documentation command, such as HELP ERROR = E-NOT-FOUND in response to which the system provides documentation regarding the error whose mnemonic is E-NOT-FOUND.

Until now, documentation of this type has been defined entirely from the interior of the system, i.e., by the designers of the system. However, according to the invention, users of a compute system that provides direct documentation are given the ability to define "user-specific" documentation for a given documentation command by specifying modifications to be made to that system in the "system documentation" ie the documentation which would otherwise be provided by the system.

(The term "user" as used herein includes not only a single individual but also a set of individuals, such as the individuals, who access the system under a given account number.)

It is, of course, necessary for the system documentation to remain intact so that it can be made available to other users either in its original form or modified by such other users. In preferred embodiments 30, this is accomplished by maintaining one or more system documentation files and additionally maintaining one or more user documentation files for each user who wishes to take advantage of engaging user-specific documentation. More specifically, 8301935 «* 2, the system files contain the system documentation. The user files contain documentation texts provided by the user, accompanied by instructions on how to use these texts to modify the system documentation. In other words, the user files contain information indicating how the user-specific documentation and the system documentation associated with one or more documentation commands differ. When a particular documentation command is given by the user, the system accesses the set documentation files and user documentation files as required and provides the appropriate user-specific documentation.

The invention will be explained in more detail below with reference to the drawing. In the drawing: Fig. 1 shows a block diagram of an information processing / communication system in which the invention is applied; FIG. 2 is a block diagram of a multi-computing node in the system of FIG. 1; fig. 3 shows a program package, which within the node according to fig. 2 is performed and which comprises a direct documentation facility 20 according to the invention; FIG. 4 is portions of system and user information base storage areas maintained in the node of FIG. 2; FIG. 5 shows the type of system documentation records maintained in the system storage area; Fig. 6 shows the type of user documentation records maintained in the user storage area; Figures 7-9 flow charts of the direct documentation facility; and FIG. 10 shows system, user and output registration lists provided by the direct documentation facility during its operation.

Table I below shows the system documentation, which is returned to a user of the arithmetic system of Figure 1 in response to the documentation command HELP COMMAND = CALL.

8301935 V * 3

TABLE I

XX XX

CALL

X USE *

PACKAGE - SPHP

call (nsa =) / asa / 5 (mode = / mode /) X EXPLANATION *

The call command causes the named program to run.

* ARGUMENTS * 10 NSA:

The program at the determined NSA is implemented.

MODE:

The post mode is changed to the specified value before the program is finished. The mode can be a common, transparency or class specific mode.

According to the invention, users of the system acquire the ability to define user-specific documentation for a documentation command qn by specifying modifications to be performed on the system documentation, i.e.

20 the documentation, which would otherwise be provided by the system in response to the relevant documentation command. For example, Table II shows a version of the system documentation, indicated in Table I, as modified by a user to provide a "user-specific" documentation for the "call" command.

TABLE II

25 304 CALL HK

X USE * call <network default address j> (mode = common or class specific mode})

* NOTE X

30 Programs are "named" by a 10-digit network standard address (NSA). The call command causes the named 8301935 4 * 4 program to run.

* ARGUMENTS * NSA:

The program is run at the particular NSA.

5 MODE:

The post mode is changed to the specified value before the program is run. The mode can be a common, transparent or class specific mode. The "transparent" mode is not currently being used and should not be used.

10 * EXAMPLE * call 0451271234 mode = class specific mode

This command invokes the Standard Customer Control Program and puts your mail in "class specific" mode.

It is noted that the "use" section has been captured, a sentence has been added at the beginning of the "notes" section, a sentence has been added at the end of the "argument" section and a new one has been added "preview" section has been added.

Fig. 1 shows a system in which the invention is applied. The system provides an integrated information processing / communication service for a number of users and comprises a number of nodes 10, which are located in the area of the service provider. One or more digital calculators are located at the heart of each node, as will be described later. A plurality of information posts 10a and host calculators, 25 or hosts, 10b are connected to nodes 10 via appropriate information lines. Most posts and hosts belong to the users and are located on their premises. Some, however, belong to the seller and are used, for example, for system administration. The nodes 10 communicate with each other via a packet-switched transport network 15. The nodes are connected to the network via respective connecting lines 11, which carry information at 56 kb / s using a protocol adapted to the CCITT standard X.25. Different nodes of the nodes can be assigned to certain functions, such as billing, provision of services, maintenance, etc.

The communication service gives the users an 8301935 * '* 5 number of capabilities. These include a time-shared execution of user and vendor-supplied application programs stored in the nodes; storing user information in information bases maintained in the nodes; supporting "software" "building blocks" / which provide services such as formatting, command-interpretation, form facilities and the like to be called by the user program; a distributed processing capability, whereby processes running in different nodes can be linked on a time-critical basis to processes running in other nodes; and a service for collecting and transporting messages.

Pig. 2 shows a block diagram of an individual node of the nodes 10. The node illustratively includes two node processors 20 and an information base processor 26. Each of these 15 processors is, for example, a Digital Equipment Corporation (DEC) VAX 11/780 computing device, which is connected to the DEC -supplied VMS operating system works. The node further includes an additional VAX 11/780 processor 28, which can take the place of either the information base processor or one of the node processors. Other nodes of the nodes 10 (Fig. 1) may have fewer or more than two node processors depending on the expected processing demand. Communication between the processors is via a line 25, which is illustratively a PCL (parallel communication link) line provided by DEC.

For example, mass storage units 21 disks 25 interact with each node processor and mass storage units 27 interact with the information base processor 26. The mass storage units 27 have two ports with the additional processor 28 and the latter can therefore access the units. For example, general purpose input / output (I / O) cooperates with each of the four processors (29/29).

At least one front processor 22 also cooperates with each node processor, which provides a link between the node processor on the one hand and associated stations of the stations 10a and the hosts 10b on the other. The front processors 22 are, for example, image IBM Series / 1 computing devices operating with the IBM-supplied RPS operating system. Each front processor communicates with its respective node processor using 8301935 6 of an X.25 protocol. DEC-supplied "firmware", which controls a DEC-supplied microprocessor 23, performs the DTE function in level 2 (the "connector" level) of the protocol. Another microprocessor 24, which interacts with each node processor, 5 serves a similar function with respect to X.25 communications over the connector 11.

The node processors 20 serve to run programs on behalf of the users and the merchant. To this end, the mass storage units 21, which cooperate with each processor, are primarily, if not exclusively, used to support the processing currently performed in that processor. Basically, all data, programs and other files, both those belonging to the user and those belonging to the seller, are stored in an information base contained in the mass storage devices 27. The latter serves to manage the information base and ensure that the node processors have access to it.

The structure of a typical vendor-supplied application program package, referred to as the message application package 20 "MAP), is shown in FIG. 3. This program package provides the user with services such as text formatting, the ability to create and broadcast messages, and various basic information services.

MAP consists of a main program 31, which is linked to a number of utilities, which are called subroutines by the main program. These utilities include the formatting device 32, which provides the text formatting ability; the set / capture post-parameter utility 33, which allows the user to acquire and set various parameters associated with his or her post; the command parser 34, which accepts a command line from the user, identifies the command verb (e.g. "calling" or "helping"), converts it into an internal form, and packages the arguments into a form suitable for the utility to which the command should be executed; the menu facility 35, which provides different menus of choices for the user and, depending on the choice or choices of the user, provides further menus and initiates any action on behalf of 8301935 7; and the direct documentation facility 36 of the invention.

Other program packages provided by the seller / offered for illustration to users (but not indicated in the drawing) include a Standard Customer Control Package (SCCP), which. provides the user with a mechanism for performing functions such as enabling and disabling programs and stations; and a Standard Parameter Handling Package (SPHP), which provides a function corresponding to that of utility 33. Each of these program packages is associated with a respective set of utilities, which at least include facility 36.

The storage area in the information base is of two types - system storage area and user storage area. As shown in Figure 4, the system storage area 40 includes, for illustrative purposes, a number of system documentation files 400. Five files are explicitly indicated. These are command documentation files 401, 402, and 403, a glossary file 404, and an error document file 405. Files 401, 402, and 403 include registrations, each containing system documentation pertaining to a particular command, recognized by 20 respectively. MAP, SCCP and SPHP. The glossary file 404 includes entries, each containing the definition of a particular term used in the system. An error file 405 includes records, each containing information regarding a particular error or alarm condition detected by the system and reported to the user during execution of one of the program packages.

In the information base there is a different storage area for each user and Fig. 4 shows the user storage area 45, which belongs to one particular user. According to the invention, the user storage area 45 includes user documentation files 450, the records of which contain user-supplied documentation texts, accompanied by instructions on how to use these texts to modify the system documentation for one or more documentation commands. In other words, the user documentation files contain information indicating how the user-specific documentation and the system documentation, 8301935 8 associated with one or more documentation commands, differ from each other. Their files in the user storage area were obtained for illustrative purposes using the formatting device 32.

In this example, the user chose to provide 5 documentation information for a) commands used in MAP, b) errors. To this end, two user files - MAP command documentation file 451 and error documentation file 452 - are created in the user collection area. For illustrative purposes, the names of these files are identical to the corresponding system documentation files 10 i.e. files 401 and 405. Therefore, once the documentation facility 36 has obtained the name of the appropriate system documentation file, it must be opened, as will be discussed later, the facility also provides the name of the appropriate user documentation file to be opened (if one is the same.

15 position exists).

Each of the program packages includes a respective information structure, which is referred to as an "environment". The environment for each package contains the filenames for the system documentation files associated with that particular program package. More specifically, the environment 310 associated with MAP ( indicated in Fig. 3) contain error, glossary and command file names, such as Error.doc, Term.doc and MAP.doe, which are the names of the respective files 405, 404 and 401. For example, when the documentation facility 36 contains the command documentation, associated with MAP, the facility consults environment 310 to determine the name of the system documentation file to be accessed. The environments associated with SCCP and SPHP each include the same error and glossary file names as the MAP environment as uniform error mnemonic sets and uniform terminology are used throughout the system. However, programs used in each program package vary. Thus, the SCCP and SPHP environments contain respective command documentation file names - for example SCCP.doc and SPHP.doc - which are the names of the respective files 402 and 403.

Each entry in the system and user documentation files is indicated by a "key", the value of which is 8301935. «9 is the conmando, term or error nemonic to which the registration belongs. Therefore, a registration in either a system or a user file containing the documentation for a particular command is recovered, for example, by specifying that command as the pointer key 5 in the information base readout.

The type for a system documentation record, ie a record in one of the system documentation files 400, is shown in Fig. 5. The registration begins with a field limiter - for example the symbols M ft - followed by an optional master registry flag and associated end limiter, at least one first section header and for each section header, a section text, all of which are separated by MW limiters.

The value of the master registration flag can be the symbol "C", which symbolizes "continuation" and indicates that the documentation associated with the corresponding designation key is too long to be included in a registration and therefore continues in a or more further registrations. (Each of these further registrations is indicated by a key, which is formed by adding a number to the key under which the first registration is designated, eg call 1, call 2, etc.).

The main registration flag can also be the symbol "M", which symbolizes "menu". This flag indicates that the registration in question does not contain actual documentation but instead the name of a menu and that when such registration is encountered by the documentation facility 36, the latter must call the menu facility 35 and specify this menu as the menu to be displayed to the user. This type of registration is used, for example, when the system provides documentation for a set of command verbs, such as "enumerate file", "enumerate 30 commands", "enumerate address lists", etc., and users are expected to use the incomplete documentation command HELP LIST can give.

In that case, the command documentation file will include a registry, indicated under the "enumerate" key, which includes an "M" as its main registry flag and the name of a menu, which the user will query 35 as to what type "list" command he or she wants documentation.

8301935 10

The section headings in the system documentation record shown in Fig. 5 are sets of symbols, such as the headings USE and EXPLANATION in Table I. The section texts are sets of symbols, which include the texts that follow each section head.

5 (Another type of registration, which is used with the system documentation files, and which is not of the type shown in Figure 5, simply includes a pointer key with no initial limiter.

The documentation facility 36 responds when it encounters such a record by providing immediate access to the record indicated under that key. This mechanism allows the system to automatically correct certain expected user errors. For example, a record provided with the entry "finish program" can be indicated under the key "finish", which is not a valid command. Therefore, if the user wishing documentation for the "finishing program" command incorrectly issues the documentation command HELP COMMAND = RUN, the documentation facility will first retrieve the specified registration under the key "finishing". When the facility finds that this record simply includes the entry "finishing program", the facility will immediately proceed with the recovery of the registration indicated under "finishing program", automatically correcting the user's error.).

The type of a user documentation record, ie a record in one of the user documentation files 450, is shown in Fig. 6. This includes an initial delimiter, optionally one or two main registration flags, at least a first section header and after each section header an optional section flag and section text, all of which are separated by limiters.

The main registration flag field may include a "C" which, as before, indicates "continuation". The field can also include either an "R" or an "N". The "R" symbolizes "replaced" and the "N" symbolizes "new". These flag values can be used interchangeably, each of these values being an instruction indicating that the totality of this user documentation record should be used instead of the totality of the corresponding system documentation record.

8301935 11

The section headings and section texts in the user documentation records are analogous to those in the system documentation records and need not be further discussed here.

The section flag can have one of four values -5 "A", "P", "R" or "N". "A" and "B" symbolize "after" and "before" and their respective instructions, which indicate that the section text must be added in the user registration either after or before the section text of the section with a corresponding heading of the corresponding system documentation registration. "R" and "N" are again interchangeable instructions, which symbolize "replaced" and "new".

Each of them indicates that the respective section text should replace the section text of the corresponding heading section of the corresponding system documentation record. If the section flag is omitted, the section is treated as if the section flag value was "A". If the section header of the user documentation record is not the same as the section header of a system documentation record, the section flag value becomes irrelevant, as will be seen later.

Before proceeding to the flow chart according to Figure 7-9, it is preferable to discuss the type of documentation commands in more detail on this point. As already noted, the user can issue commands, such as HELP COMMAND = CALL, HELP TERM = BILLING-IDENTIFIER and HELP ERROR = E-NOT-FOUND, in response to which the system will provide the full documentation for the particular The command, the term or error in question is available, as modified (if it is) by the user. Optionally, the user can eliminate "COMMANDO =" in a command documentation request, for example HELP CALL. Another option is that the user can specify that only a particular section or 30 sections of the documentation should be displayed, eg HEL? CALL SECTION = USAGE SECTION = EXEMPLE. Yet another option allows the user to obtain documentation from the command documentation file associated with a program package that is different from the package he or she is currently using, provided that the user knows the node of that file. For example, a user of MAP

for example, give the command HELP CALL FILE = SCCP.doc SECTION = ARGUMEiriS

8301935 12 and thereby obtain documentation of the arguments for the "call" command, as used in SCCP.

Figures 7-9 show a flowchart of the direct documentation facility 36, which, as already noted, is called -5 as a subroutine and is hereinafter also referred to as "the routine".

Fig. 7 more specifically shows the record recovery portion of the routine. This begins at step 701 by examining the arguments fed to it by the command parser 34 to determine which documentation is being requested correctly. If, as determined at step 703, the user has given an incorrect documentation command, for example HELP ERROR, the documentation facility calls the menu facility 35 at step 704.

The menu facility, by eliciting user responses, will attempt to determine what documentation the user desired. Once established, the menu facility forms a documentation request on behalf of the user and returns it to the documentation facility.

For illustrative purposes, it will be assumed that the user executes • MAP and has issued a documentation command requesting documentation for the "call" command. As indicated at 706, it is now determined whether the latest documentation requested by this user was for the same command currently requesting documentation, namely "call". (This documentation is still available in the master registration list 1050 (to be discussed later).). If this is the case, the control goes directly to the marking / printing part of the routine (fig. 9).

Otherwise, the documentation facility now determines, at step 709, the name of the relevant system and therefore the user command documentation files - in this case MAP-doe. As indicated at 711, the routine dam consults a table, which maintains the routine of the names of open documentation files to determine whether a file or files, named MAP.doe, is already open respectively. If not, an attempt is made to open a file of this name in both the system and user storage areas, as indicated at 714.

8301935 13

At this point, it can be assumed that a system file is open under that name since the system file is always present. However, a user file for the type of requested documentation may not be present. Therefore, at step 717, it is determined whether there is essentially an open user file called MAP.doe. If not, the routine proceeds directly to step 732, where the registration or (in case of continuation) registrations containing the documentation for the particular command is recovered.

10 If, on the other hand, a user file called MAP.

doc, open, at step 721 an attempt is made to recover from it used records (registrations) documenting the command "call". If, as determined at step 724, no such registration is present, which means that the user has not provided documentation for the "call" command, the routine simply proceeds to step 732 again. However, if a user registration is present, its main recording flag field (Fig. 6) is checked for the presence of an "R" or "N". This would indicate that the user documentation for the "cal!" Command must replace the entire system-20 documentation, in which case step 732 is skipped as the system registration, which contains the documentation for the "call" command, is not necessary. is. On the other hand, if the user registration is not such a replacement registration, the system registration must first be recovered and, like first, step 732 is performed.

At this point, control passes to the registration processing portion of the documentation facility, as indicated at 734. This portion of the routine, indicated in Figure 8, begins at step 801, with the previously recovered system documentation registration, if any. , is examined and analyzed. This involves performing entries in a so-called system record list 1010, which is shown in Fig. 10. The system record list is a predetermined system of information structures system blocks 1020 - each of which includes storage locations for holding the following information. information from or about a respective section of the system registration: the section header, which is stored at location 1021; a pointer to 8301935 14 the location of the section text, which is stored in the location 1022; and a count of the number of symbols in the text stored in the location 1023.

Referring again to Figure 8, the routine now passes to step 803, wherein the previously recovered user documentation record, if any, is similarly examined and parsed in a user record list 1030, which is also shown in Figure 10. The user registration list includes user blocks 1040. In addition to a section header storage locations, a text pointer and a symbol count, which are stored in locations 1041, 1042, and 1043, each section, a storage location 1045 for the section flag value (A, B) , R or N), which has been described above.

The system and user registration lists are used to provide a so-called output registration list 1050, as will be described below. This list includes a set of output blocks 1060, each of which includes a collection site for the following information: a section header, a pointer to the first text, a symbol count for the first text, a pointer to a second text, a symbol count for the second text and a print flag, which are respectively indicated at 1061 to 1066.

More specifically, the routine fills out the output recording list 1050 by executing a loop, as indicated at 808 in Fig. 8. With each run through this loop, routine 25 examines a contiguous block of system blocks 1020 and determines at step 811 whether there is a modified section header in one of the user blocks 1040. If not, the routine proceeds to step 814, copying the section header from location 1021 in the system block to location 1061 in the next available block of output blocks 1060. In addition, the text pointer and symbol count of positions 1022 and 1023 of the system block in positions 1062 and 1063 of the output block are copied as the first text pointer and the first symbol count, respectively. The second text pointer in the output block, accumulated at position 1064, is released to a zero chain. The routine then runs around to process the next system block.

8301935 15 t

On the other hand, if a section header is present in one of the user blocks 1040, which is adapted to the section header in the system block currently under consideration, the routine copies this header at the location 1061 of the next available output block at step 5816 and then, at step 819, sets the text pointers (and corresponding symbol counts) in the output block according to the value of the section flag stored at the location 1045 in the user block. More specifically, if the section flag value is UA "(before" after "), the first and second text pointers stored in the 1062 and 1064 position of the output block are given the values of the text pointers. are stored at the respective locations 1022 and 1042 of the system and user blocks, and the same is true for the symbol counts If the section flag is "B" (for "for"), the output block test pointers and symbol counts are assigned the same values but in reverse order. If the section flag is "R" (for "replaced") or "N" (for "new"), the documentation for the particular section must be replaced entirely by the user documentation. In this case, the first text pointer and the symbol count in the output block are given the values of the user block test pointer and symbol count, and the second output block text pointer is made to a zero chain. As indicated at 821, the respective user block is now marked as being "used" - which is indicated by way of illustration because its section head has been made a zero chain.

Once all system blocks 1020 have been processed in this manner, the loop is exited and the routine proceeds to step 824. Here the user registration list 1030 is scanned for any unmarked user blocks, i.e. any blocks whose section headings are not zero chains. The information from such a user block is copied into a respective block of the output blocks in the same manner as the information in a system block, which does not have a modified user block, is copied into an output block, as described above for step 814. From the above, it appears that the section flag value is irrelevant in this case.

As indicated at 826, the routine now transitions to the section marking print portion thereof shown in Fig. 9.

8301935 * 16

If the documentation command has specified that only certain sections are to be displayed, as determined in step 901, the print flag is set in the appropriate output block, as indicated in step 903. Otherwise, the print flags are set in all output blocks as indicated in step 904.

The documentation is now ready to be "printed" i.e. displayed for the user. First, the registration key used for registering the registration is capitalized and printed with double asterisks as the main header at step 908 (for example, CALL in Tables I and II). Thereafter, each block of the output list 1050 is sequentially considered through a loop starting at 911. In the loop, each output block is first checked at step 913 to see if the block is marked for printing. If not, consideration 15 moves to the next block. However, if the block is marked for printing, the routine goes through steps 915, 916 and 919, where the section header is capitalized and printed, the first text specified in the output block is printed, and the second text , if available, is printed.

Once all the output blocks have been considered, the routine returns to its caller.

8301935

Claims (4)

1. Direct documentation method for use in a calculation system, characterized in that individual users of the system are provided in response to the giving by the users of a given documentation command, system documentation associated with the determined documentation command, and to at least one other user of the system in response to this other user's giving of the particular documentation command, user-specific documentation previously defined by the other user is provided. Device for applying the direct documentation method for use in an arithmetic system according to claim 1, characterized by first means (36, 40; 1010, 1050) for providing individual users of the system in response to these users providing provide a particular documentation command, system documentation associated with that particular documentation command, and second means (36, 40, 45, 1030, 1050) to communicate to at least one other user of the system in response to giving by this other user of the particular documentation command, to provide user-specific documentation previously defined by this other user. 20 Device according to claim 2, characterized in that the first and second members are provided with common means (40) for storing the system documentation associated with the given documentation command and for storing system documentation associated with other documentation commands , which may be given by the users of the system, and the second means further comprising means (45) for storing one or more user documentation text associated with at least the determined documentation command, and storing an instruction associated with with each user documentation text, indicating how that user documentation text should be used to modify the stored system documentation associated with the particular command, and means (36, 1030, 1050, 1010) to provide the user-specific documentation according to each of the instructions. Device according to claim 2, characterized in that the first and second members 8301935, 18 are provided with common means (40) for storing the system documentation associated with the determined documentation command and for storing system documentation associated with it. in other documentation commands, which may be given by system users, the system documentation associated with each documentation command comprising one or more sections of system documentation text, and the second means further comprising means (45) for storing one or more user documentation text associated with at least the specified documentation command, and for storing an instruction associated with each user documentation text indicating whether to add this user documentation text to a corresponding system documentation text to replace a corresponding system documentation text or to be used as a separate section in the user-specific documentation, the second members (36, 1010, 1050, 1030) further including means for providing the user-specific documentation according to each of the instructions . 8301935