SFCBuffers.pl

SFCBuffers.pl is the front-end to the complete tool set.

SFCBuffers.pl Use

•  -cdb <file.cdb>
  The tools accept a 'colon-delimited database' file, similar in use to most config files. The format of a row in the .cdb file is

  ::TAG::fob data[:...]

  If there are no colons in the data field, it is treated as a scalar. If there is/are, then the data field will be split on the : and treated as an array. Because arrays require internal handling on a case by case basis, they are limited to ::IN:: type tags (see below). Specifically, other type tags (CDB, FLAG, etc) are not array-aware.

In general, a .cdb file is a superset of the command line arguments available -- Certain type tags found in the .cdb files have no analogue with the command line arguments. To generate a .cdb file based on the current input arguments, which can then be edited using any common plain-text editor, use the -v flag on the command line. The .cdb structure that corresponds to the other input command line arguments will be output to the command line; exceptions will be noted.

• ::IN:: tags in a .cdb file are treated like command line arguments; they generally have side effects (additional processing happens based on these settings).

• ::FLAG:: tags in a .cdb file are local arguments, and do not have side effects in the basic installation. It is possible to extend the scripts to treat specific ::FLAG:: tags with additional processing. These extensions are local installation specific. Additionally, later revisions of the installer will not place anything in the relevant directories (see the sub-directories under Personalities for examples).
  

• -cstruct <StructName> {nbsp}{nbsp} default: cmd

  • CDB: ::IN::StructName cmd
    By default/per convention, the output sub-function code stub will use 'cmd' as the generated c struct name for use by cmds_scanf. To use a different name, set it here and it will be propagated where necessary (for example, the generated cmds_scanf call will reference the new CommandName, rather than cmd).
    This will not change the behavior of the internal generated code; the "response" struct will still be the lower-cased classname value.
    

• [-pattern] <pattern> {nbsp}{nbsp} no default

  • CDB: '::IN::inpattern <pattern>'
    The -pattern mark is optional. If not found, all arguments will be parsed looking for one that matches the cmds_scanf pattern semantics.
    

• -fields <fieldname:fieldname:fieldname:...> {nbsp}{nbsp} no default

  • CDB: ::IN::innames <name,name,name,...>

  • CDB: ::IN::fieldtags <lenSpecifier>:<ptrSpecifier>[:<postfixBool>]
    These are the names of the fields (one per token) that match the supplied pattern. The array of names are separated on the command line or in the .cdb file using a comma. Use of a : will cause them to be split into an array too soon, so as a special handling step, if you accidently use : here, it will be converted back to commas before processing.
    Pattern marks that result in two cmd fields (vN, *, etc) still only require a single name. vN field names will prepend either l_ or p_ (or see below) to match the multiple fields requirement in the structure.
    The initial l_ and p_ for multi-field values can be changed via .cdb file input as shown above. Whatever is in front of the : will be placed in front of the provided name for length fields, and whatever is after will be placed in front of the provided name for pointer fields. At least one must be provided ('l_:' and ':p_' are valid, and will result in 'l_field'/'field' and 'field'/'p_field' respectively). The postfixBool field may be 0 (default) or 1. When 1, the values supplied for the specifiers will be postfix modifications instead of prefix.

    On processing, fieldnames (like 'flags,key,cruft') will be matched to sub-pattern specifiers (like 'u4v2*'), from left to right. It is expected that the sub-pattern count should equal the fieldname count, but it is not an error if there is a mismatch. The script will match sub-patterns to fieldnames so long as they are available, and then request additional (if necessary) at the command line. If the pattern requires fewer fieldnames than supplied, a warning will be shown, and remaining fieldnames will be discarded.
    There is a special case for the '+*+' (remainder) mark, in that if a fieldname is not supplied for it, "bkkt" (bucket) is used.

    cf comments in *-go*, related to warnings. In this case, if the fieldnames supplied don't match to the pattern specifiers, the tool will exit with an error message.

    
    

• -class <ClassName> {nbsp}{nbsp} no default

  • CDB: ::IN::ClassName <ClassName>
    This is the class name used for the host-side OOP languages (Java, C++). Additionally, it is used as the struct name when this pattern is used as a response value.
    When C is generated, you will get both a cmd struct in the generated _ext_ stub, and a <classname> struct (note the de-capitalization) in the <ClassName>.h header file:
    

• * -dev <devstring> {nbsp}{nbsp} default: 3001@127.0.0.1

  • CDB: ::IN::dev <devstring>
    The supplied device string is used for the generated Test applications, and is in use the same as Dev=<devstring>, as used by csadm, cxitool, etc.

• -go

  •  CDB: ::IN::go [1|0]
    If you don't need interactivity, -go will cause the tools to run without.
    Things which are warnings while interactive are promoted to errors when in -go, and the tools will not run to completion.

• -mdl <ModuleName> {nbsp}{nbsp} default: exmp

  • CDB: ::IN::ModuleName <ModuleName>
    Used to tell the tools what the target module name is (SDK/cs2/mdl/<modulename>), like 'exmp'

• -mid <module_id> {nbsp}{nbsp} default: 0x100

  • CDB: ::IN::mID <module_id>
    Used to tell the tools what the target module ID is (0x100 .. 0x17f). There are some heuristics to generate a valid mID based on the input. If it fails, you get a warning and the value 0x13a is substituted for the unexpected module id value.

    cf behavior for -go

• Single SFC:

  • -sfc <sfc_id> {nbsp}{nbsp} default: 0

  • CDB: ::IN::SFC <N>
    Used to tell the tools what the target sub-function code for this pattern is.

• A complete Module's SFCs

  • Repeatable: -sfc <sfc_id>:<sfc_name>:<inpattern>[:<outpattern>]

  • ::IN::SFC_Count <N>

  • ::SFC::0 <name>:<AStructName>[:BStructName]

  • ::SFC::(N-1) <name>:<AStructName>[:CStructName]

  • ::STRUCT::AStructName <pattern>:<fieldname>[:<fieldname>[:...]]

  • ...

The IN::SFC_Count value is a hint to the loop of how far to look for different SFC::fob indexes, 0..(N-1) will be looked for. Values can be skipped. For each found, the template processing will generate an _ext_ stub method, with the input and output structures and handling based on the STRUCT::<StructName> values requested (behavior for the given struct will be determined by its location in the ::SFC::n line).

If the SFC does not process the input l_cmd/p_cmd data, or expects a zero-length p_cmd value, the input struct name can be absent:

`::SFC::5 getdefaultkey::KeyBlob`

• -files <glob> {nbsp}{nbsp} default: *.*

  • CDB: ::IN::files <glob>
    By default, the template processing engine will attempt to process all files found in the templates directory, based on patterns built into the file names themselves. The -files argument can subset this, to only target a specific file or set of files. The actual value supplied will be treated as if it were wrapped by wildcards, so a '-files EXT' will cause processing to happen to any file with EXT in the filename.

    To limit template processing to a specific personality (or personalities), see *-plist <Languages>* . -plist and -files can be used together.

• -plist <Languages> {nbsp}{nbsp} default: C:Cpp:Java:Txt
  CDB: '::IN::plist C:Cpp:Java:Txt'

  Ordinarily, the template processing engine will attempt to process all files found in the templates directory, based on file type. Each supported personality (see the .../Personalities directory) will have its own sub-directory in the templates directory, which provides the files it expects to work on.
  To limit processing to one or more specific personalities, use plist to list it/them.
  To process specific files based on filename, see *-files <pattern>* . -plist and -files can be used together.

• -t <templateDirPath> {nbsp}{nbsp} default: ./templates/

  • CDB: ::IN::template <templateDirPath>
    The root directory of where the templates should be sourced from.

• -answ <SymbolName> {nbsp}{nbsp} default: (unset by default)

  • CDB: ::IN::AnswStruct <SymbolName>
    If set, the value supplied will be substituted into the generated artifacts where an Answer Struct is used or expected. The templates use the replacement tag #AnswStruct#. Also, The 'AnswStruct' replacement tag symbol name is treated both as the symbol to use, but also its existence is seen by the preprocessor as the token to cause the output to be there:

• -v {nbsp}{nbsp} default: (unset by default)
  Slightly more verbose output.
  Also, If verbose is set, the script will dump a .cdb file format that provides the command-line supplied configuration. The format, saved as a .cdb file, can be used via -cdb <format> to rerun the same configuration. CDB files can be edited.

• -get <prefix:suffix> {nbsp}{nbsp} default: 'get:' (result is get<FieldName>, for each FieldName)

  • CDB: ::IN::get <prefix>:<suffix>

• -set <prefix:suffix> {nbsp}{nbsp} default: 'set:' (result is set<FieldName>, for each FieldName)

  • CDB: ::IN::set <prefix>:<suffix>
    These provide support for different coding conventions, for getters and setters.
    The get and set targets expect value pairs (the two values are separated by a colon, which must be there).
    The field name will be capitalized for this use.The default values, applied to a symbol name foo, result in getFoo(...) and setFoo(...). If you move the get/set to after the colon, the result would be Fooget and Fooset. You can put something on both sides, like public:Set, and the result would be publicFooSet(...).