help mata st_lchar() undocumented
-------------------------------------------------------------------------------
Title
[M-5] st_lchar() -- Obtain/set "long" characteristics
Syntax
void st_lchar(basename, charname, string scalar s)
string scalar st_lchar(basename, charname)
void ado_intolchar(basename, charname, macname)
void ado_fromlchar(macname, basename, charname)
where basename, charname, and macname are string scalar.
Description
These functions concern obtaining and setting characteristics that might
be longer than 67,784 characters. To obtain and set characteristics in
the usual case, you code
s = st_global("_dta[example]") // obtain
st_global("_dta[example]", s) // set
See [M-5] st_global.
The maximum length of a characteristic is 67,784 characters whether you
are running Stata/IC, Stata/SE, or Stata/MP. In Stata/SE and Stata/MP,
however, macros can be longer than that. These functions allow saving
Stata macros in characteristics and vice versa, and they handle the
problem that macros can exceed the maximum allowed length of Stata's
characteristics.
st_lchar() is for use by Mata programmers:
1. st_lchar(charname, basename, s) saves s in "long" characteristic
basename[charname].
2. st_lchar(charname, basename) returns the contents of "long"
characteristic basename[charname].
3. st_lchar(charname, basename, "") can be used to delete "long"
characteristic basename[charname].
ado_intolchar() and ado_fromlchar() are for use by Stata ado-file
programmers:
1. ado_intolchar(basename, charname, macname) saves the contents of
local macro macname in "long" characteristic basename[charname].
2. ado_fromlchar(macname, basename, charname) places the contents of
"long" characteristic basename[charname] into local macro
macname.
3. Ado-file programmers use the same function as Mata programmers to
delete a characteristic: st_lchar(charname, basename, "")
deletes "long" characteristic basename[charname].
Remarks
Stata macros can be longer than Stata dataset characteristics. The
maximum length of a characteristic is 67,784 characters. Macros are
longer than that when the user is running Stata/SE or Stata/MP. How much
longer macros can be depends on maxvar because maximum macro length is
defined to be sufficient to hold all the names in possible Stata
datasets, with a space between, plus some more.
In regular Stata/IC, the maximum number of variables is 2,047. Variable
names can be 32 characters, so macros must allow at least 2,047*33 =
67,551 characters.
In Stata/SE and Stata/MP, the maximum number of variables is 5,000 by
default and can be set up to 32,767. Thus, the maximum length of macros
must allow at least 5,000*33 = 165,000 to 32,767*33 = 1,081,311
characters. Yet, in all these cases, the maximum length of a
characteristic remains fixed at 67,784 characters, meaning that saving
all the variable names in one characteristic is not generally possible.
Programmers will sometimes want to save a varlist in a characteristic and
the varlist might be long. Stata saves characteristics in the Stata .dta
dataset and programmers save information in characteristics when they are
a property of the dataset rather than of the current session or the
current analysis. A program providing data certification, for instance,
might need to save the names of the variables so that those names could
later be compared with the current names to determine whether any
variables had been added or dropped.
These functions provide the solution to the different-length problem.
Think of these functions as creating, reading, and writing
basename[charname], even though these functions in fact create, read, and
write basename[charname1], basename[charname2], ..., using however many
separate characteristics are necessary to store what needs to be stored.
For the Mata programmer, st_lchar(charname, basename, s) saves s in
basename[charname1], basename[charname2], .... st_lchar(charname,
basename) returns what was previously set in basename[charname1],
basename[charname2], ....
For the Stata ado-file programmer, the same features are provided, except
that values are obtained from and stored in local macros.
ado_intolchar(basename, charname, macname) saves the contents of macname
into basename[charname1], basename[charname2], ....
ado_fromlchar(macname, basename, charname) retrieves the contents of
basename[charname1], basename[charname2], ..., and stores the result in
macname.
In all these functions, you do not have to keep track of how many
characteristics are actually used. Think of the functions and storing
in, fetching from, and deleting basename[charname], even though that is
not literally true and, in fact, basename[charname] is never created.
The actual characteristics are basename[charname1], basename[charname2],
....
Example 1 -- Ado file usage
In an ado-file, you want to save the contents of local macro varlist in
characteristic _dta[datacert_vl]. Ordinarily you would code
char _dta[datacert_vl] `varlist'
but you are worried that `varlist' might be too long for
_dta[datacert_vl]. The solution is to code
mata: ado_intolchar("_dta", "datacert_vl", "varlist")
There are no typographic errors in the above. You pass the names of the
entities -- including the macro -- and not their contents.
In another part of the code, you want to pull back into macro baselist
what was stored in _dta[datacert_vl]. Ordinarily you would code
local baselist `_dta[datacert_vl]'
but, because you used st_intolchar(), you must not do that. Instead, you
code
mata: ado_fromlchar("baselist", "_dta", "datacert_vl")
In yet another part of the program, you want to clear the
characteristics. To clear _dta[datacert_vl], ordinarily you would code
char _dta[datacert_vl]
but, because you used st_intolchar(), you must not do that. Instead, you
code
mata: st_lchar("_dta", "datacert_vl", "")
Example 2 -- Mata usage
In Mata code, you wish to set _dta[datacert_vl] to contain the contents
of string scalar s. You code
st_lchar("_dta", "datacert_vl", s)
To read back into s what is stored in _dta[datacert_vl], you code
s = st_lchar("_dta", "datacert_vl")
To delete the characteristic _dta[datacert_vl], you code
st_lchar("_dta", "datacert_vl", "")
Conformability
st_lchar(basename, charname, s):
basename: 1 x 1
charname: 1 x 1
s: 1 x 1
result: void
st_lchar(basename, charname):
basename: 1 x 1
charname: 1 x 1
result: 1 x 1
ado_intolchar(basename, charname, macname):
basename: 1 x 1
charname: 1 x 1
macname: 1 x 1
result: void
ado_fromlchar(macname, basename, charname):
macname: 1 x 1
basename: 1 x 1
charname: 1 x 1
result: void
Diagnostics
All functions abort with error if names are malformed. Requesting the
contents of a characteristic that does not exist returns "". If s is
stored in a characteristic and read back, the original spacing (lack of
blanks, multiple blanks, etc.) of s is preserved.
Source code
st_lchar.mata
Also see
Manual: undocumented
Help: [M-5] st_global(); [M-4] stata
