Internet-Draft R. Iannella draft-iannella-admin-00.txt DSTC 08 ...
... 1998-01-01"> <META NAME="DC.Identifier" SCHEME="URI" LANG="en" CONTENT="http://metadata.
net/ADMIN/elements.html"> <META NAME="ADMIN.CreatorPersonal" LANG="en ...
www.potaroo.net/ietf/old-ids/draft-iannella-admin-00.txt - 12k - Supplemental Result -

Internet-Draft                                                

      Admin Core - Administrative Container Metadata


1. Status of this Document


This document is an Internet-Draft.  Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups.  Note that other groups may also
distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time.  It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."

To view the entire list of current Internet-Drafts, please check
the "1id-abstracts.txt" listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net
(Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au
(Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu
(US West Coast).

Distribution of this document is unlimited.  Please send comments
to <renato@dstc.edu.au> and <dcampbel@nla.gov.au>.


2. Introduction

Administrative metadata - referred to as 'Admin Core' - is useful to 
designate information about the creation and availability of other sets
of metadata. The objective of Admin Core is to provide simple
authentication to verify the integrity and provenance of information
retrieved from networked resources. The Admin Core elements are utilised
to associate date and creator information about metadata. It is
important to recognise that Admin Core is a "container" metadata element
set as opposed to a "content" metadata element set - its purpose is to
describe metadata instances.  

The Admin Core, as with other metadata elements sets, is a "core" set. 
That is, it is extensible by allowing the addition of new elements that
are specific to a community's needs. This is similar to the model 
presented by the Dublin Core Metadata Element Set [2].

Admin Core is not useful by itself. It must be used in association with
at least one other metadata element set. For example, Dublin Core [2], or
Privacy [3] metadata. This amalgamation of different metadata sets is
supported by a number of metadata encoding systems, such as the Resource
Description Framework [1] and the HTML META tag [6]. Examples are given
in Section 5.

Admin Core metadata will be used by systems and users to determine the
currency of metadata, expired metadata, and how to contact creators of
metadata.


3. Description of Admin Core Elements  

The following is the reference definition of the Admin Core Metadata
Element Set.  The evolving reference description can be found at:

        http://metadata.net/admin

In the element descriptions below, each element has a descriptive name
intended to convey a common semantic understanding of the element, as
well as a formal single-word label intended to make the syntactic
specification of elements simpler for encoding schemes. The recommended
best practice is to be case-sensitive to avoid complications in
case-sensitive environments such as RDF [1].

The element descriptions also indicate the obligations, encoding, and
repeatability characteristics for each Admin Core element in accordance
with the ISO Standard 11179 [8].


3.1  Personal Creator

     Name:       CreatorPersonal

     Definition: The person responsible for creating or modifying the
                 metadata pertaining to a resource.

     Obligation: Conditional. Either "Personal Creator" or "Corporate
                 Creator" element must appear, or both.

     Datatype:   Character String

     Maximum
     Occurrence: Unlimited

     Comment:    If possible, the comma (,) is used to separate the 
                 surname first followed by firstname. For example;
                 "Crystal, Mary"


3.2  Corporate Creator

     Name:       CreatorCorporate

     Definition: The name of the organisation by which the metadata
                 creator is employed.

     Obligation: Conditional. Either "Personal Creator" or "Corporate
                 Creator" element must appear or both.

     Datatype:   Character String

     Maximum
     Occurrence: Unlimited

     Comment:    The organisation may be a trusted third party for the
                 source of the metadata. The organisation is not
                 necessarily the entity making the resource available. 


3.3  Creator Email Address

     Name:       CreatorEmail

     Definition: The email address of the metadata Creator.

     Obligation: Mandatory

     Datatype:   Character String. Encoded to be consistent with Internet
                 Address standard RFC822 [7]

     Maximum
     Occurrence: Unlimited.

     Comment:    None


3.4  Creator Contact Information

     Name:       CreatorContact

     Definition: Information on how to contact the creator.

     Obligation: Optional

     Datatype:   Character String

     Maximum
     Occurrence: Unlimited

     Comment:    The information should be one or more of: a street or
                 postal address, a telephone number, a facsimile number,
                 and the homepage address of the creator. This provides
                 additional evidence for the existence of a trusted third
                 party.


3.5  Date Created

     Name:       DateCreated

     Definition: The date/time the metadata was created by the Personal
                 or Corporate Creator.

     Obligation: Mandatory

     Datatype:   Character String. Encoded to Date and Time Format
                 ISO 8601 [4]

     Maximum
     Occurrence: Unlimited

     Comment:    None


3.6  Date Modified


     Name:       DateModified

     Definition: The date/time the metadata was most recently modified
                 by the Personal or Corporate Creator.

     Obligation: Optional

     Datatype:   Character String. Encoded to Date and Time Format
                 ISO 8601 [4].

     Maximum
     Occurrence: Unlimited

     Comment:    None


3.7  Date Valid From

     Name:       DateValidFrom

     Definition: The commencing date of the validity of the metadata
                 description. 

     Obligation: Conditional. Single occurrence only is permissible
                 otherwise must appear in pairs with "Date Valid To"
                 element.

     Datatype:   Character String. Encoded to Date and Time Format
                 ISO 8601 [4].

     Maximum
     Occurrence: Unlimited

     Comment:    Non-administrative metadata accessed before this date
                 should be considered to be invalid.



3.8  Date Valid To

     Name:       DateValidTo

     Definition: The end date of the validity of the metadata
                 description.

     Obligation: Conditional. Single occurrence only is permissible
                 otherwise must appear in pairs with "Date Valid From"
                 element.

     Datatype:   Character String. Encoded to Date and Time Format
                 ISO 8601 [4].

     Maximum
     Occurrence: Unlimited.

     Comment:    Non-administrative metadata accessed after this date
                 should be considered to be invalid.


4. Internationalisation

All the Admin Core elements can be associated with language information
using RFC 1766 [5]. The Admin Core labels are used in the communication
of metadata between systems, with human-readable names being available
in multiple languages for client systems.


5. Admin Core Examples

5.1 HTML META Syntax

Below is an example of the use of the Admin Core metadata elements
with the bibliographic style Dublin Core metadata elements. This example
shows the HTML META syntax [6]. Admin Core elements will be assigned the
namespace of "ADMIN" for the META tag syntax encodings.


  <META NAME="DC.Title" LANG="en"
        CONTENT="Admin Core Metadata Element Specification">
  <META NAME="DC.Creator" LANG="en" CONTENT="Crystal, Jacky">
  <META NAME="DC.Date" SCHEME="ISO8601" LANG="en" CONTENT="1998-01-01">
  <META NAME="DC.Identifier" SCHEME="URI" LANG="en" 
        CONTENT="http://metadata.net/ADMIN/elements.html">

  <META NAME="ADMIN.CreatorPersonal" LANG="en" CONTENT="Rubble, Barney">
  <META NAME="ADMIN.CreatorEmail" LANG="en" CONTENT="barn@metadata.net">
  <META NAME="ADMIN.DateCreated" SCHEME="ISO8601" CONTENT="1998-01-15">


5.2 RDF/XML Syntax

Below is another example of the use of Admin Core metadata elements with
the bibliographic style Dublin Core metadata elements. This example
shows the use of RDF syntax [1]. The RDF XML Namespace for Admin Core
will be defined as: <http://metadata.net/admin/#>


  <? xml version="1.0" ?>
  <RDF xmlns       = "http://www.w3.org/TR/WD-rdf-syntax#"
       xmlns:DC    = "http://metadata.net/dc/#"
       xmlns:ADMIN = "http://metadata.net/admin/#" >

    <Description xml:lang="en" 
         about = "http://metadata.net/admin/elements.html">
      <DC:Title> Admin Core Metadata Element Specification </DC:Title>
      <DC:Creator> Crystal, Jacky </DC:Creator>
      <DC:Date> 1998-01-01 </DC:Date>

      <ADMIN:CreatorCorporate> Rubble Corp <ADMIN:CreatorCorporate>
      <ADMIN:CreatorEmail> info@rubble.com </ADMIN:CreatorEmail>
      <ADMIN:DateCreated> 1998-01-15 </ADMIN:DateCreated>
      <ADMIN:DateValidFrom> 1998-02-01 </ADMIN:DateValidFrom>
      <ADMIN:DateValidTo > 1999-02-01 </ADMIN:DateValidTo>
    </Description>
  </RDF>


6. Security Considerations

The Admin Core element set poses no risk to computers and networks.
Human clients who obtain metadata that has been incorrectly 
described (by humans) may face minimal risk in determining the
correctness of the metadata. The application of Digital Signature
technology is recommended by systems requiring high levels of
authentication.


7. Acknowledgements

The work reported in this paper has been funded in part by the
Cooperative Research Centres Program through the Department of the
Prime Minister and Cabinet of Australia and from the National Priority
(Reserve) Fund  allocation for Improved Library Infrastructure
administered by the AV-CC Standing Committee on Information Resources.


8. References

   [1] Resource Description Framework (RDF) Model and Syntax
       <http://www.w3.org/TR/WD-rdf-syntax>
       
   [2] RFC 2413, Dublin Core Metadata for Resource Discovery
       <ftp://ftp.isi.edu/in-notes/rfc2413.txt>
       
   [3] Platform for Privacy Preferences Metadata
       <http://www.w3.org/P3P>
       
   [4] Date and Time Formats (based on ISO 8601), W3C Technical Note
       <http://www.w3.org/TR/NOTE-datetime>

   [5] RFC 1766, Tags for the Identification of Languages
       <ftp://ftp.isi.edu/in-notes/rfc1766.txt>

   [6] A Proposed Convention for Embedding Metadata in HTML
       <http://purl.oclc.org/docs/metadata/dublin_core/approach.html>

   [7] RFC822 Standard for the Format of ARPA Internet Text Messages
       <ftp://ftp.isi.edu/in-notes/rfc822.txt>

   [8] ISO 11179 Parts 1-6, Specification and Standardization of Data
       Elements <ftp://sdct-sunsrv1.ncsl.nist.gov/x3l8/11179/>


 iHTML CACHE="false"> <iEQ NAME="page" VALUE="basket"> <iINCLUDE ...
... NAME="admin/makeid.inc"> <iINCLUDE NAME="admin/taxvars.inc"> <iINCLUDE
NAME="admin/shipvars.inc"> <iINCLUDE NAME="custcurrency.inc"> <HEAD> <META HTTP- ... 
edimage.ca/magasin/basket.ihtml - 1k - Supplemental Result - 

<!iHTML CACHE="false">

<iEQ NAME="page" VALUE="basket">
<iINCLUDE NAME="admin/datasource.inc">
<iINCLUDE NAME="admin/errorblock.inc">
<iINCLUDE NAME="admin/globals.inc">
<iINCLUDE NAME="admin/functions.inc">
<iINCLUDE NAME="admin/todaydate.inc">

<iEQ NAME="giveCookie" VALUE="false">
<iINCLUDE NAME="admin/makeid.inc">
<iINCLUDE NAME="admin/taxvars.inc">
<iINCLUDE NAME="admin/shipvars.inc">
<iINCLUDE NAME="custcurrency.inc">



<HEAD>
	<META HTTP-EQUIV="pragma" CONTENT="no-cache">
	<META HTTP-EQUIV="expires" CONTENT="0">
</HEAD>

<iINCLUDE NAME="template/header.ihtml">
<iINCLUDE NAME="basket_content.inc">
<iINCLUDE NAME="template/footer.ihtml">

</BODY>
</HTML>

Hungarian notation is a standard in defining variables. To use Hungarian notation you add characters to the front of a variable where the characters define the data type. The benefit of using Hungarian notation is that at one glance of the variable, you should be able to interpret both the variables data type and purpose.

For example, suppose you have a variable 'Company'. The variable name of 'Company' can indicate a company name or a company id. You would have to look at how the variable is used or find the definition to know the data type. A better variable name is sCompanyName. The 's' indicates a string of characters and the 'CompanyName' indicates the information contained in the variable. If someone runs across 'sCompanyName' in your Active Server page they will know that it is a string.

This is probably trivial if you are the lone programmer with very little code in your library. Many code bases start out that way. But a successful piece of code will be passed around and be used my many programmers. Hungarian allows the code to be easily transferred and worked on within a group of developers Common Hungarian Notation in ASP pages

Put Request parameters into variables once

Request parameters are those parameters that are passed from one web page to another in the form of:

http://www.myserver.com/page.html?Param1=XYZ&Param2=45

<%
sParam1=Request("Param1")
iParam2=Request("Param2")
%>
&ltHTML>
&ltBODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>

http://www.myserver.com/page.html?Parm1=XYZ&Parm2=45

<%
sParam1=Request("Parm1")
iParam2=Request("Parm2")
%>
&ltHTML>
&ltBODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>

<%
Dim 	iParam2 int
sParam1=Request("Parm1")
iParam2=CInt(Request("Parm2"))
%>
&ltHTML>
&ltBODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>

<%
Dim 	iParam2 As int
Dim	sParam1 As String

sParam1=Trim(Request("Parm1"))
iParam2=CInt(Request("Parm2"))
%>
&ltHTML>
&ltBODY>
<%=sParam1%> : <%=iParam2%>
</BODY>
</HTML>

Use Option Explicit

By adding the command:

OPTION EXPLICIT

Dim cObject As int

cObjects=0
For Each Object in Collection
	cObject=cObjects+1
Next Object

The trade off is that you have to do more typing, declaring all the variables, but you produce cleaner code.

Put ASP delimiters at the left hand margin unless code is in line

When writing an ASP page, you use the <% and %> delimiters so the ASP compiler knows when to interpret your code versus displaying HTML code. You can mix ASP and HTML in one of two ways (or both at the same time).

Here is an example of a poorly formatted ASP page.

<%%
sub X()
	Set RS = oConn.Execute(sQueryText)%>
	&lttable align="left">&lttr>&lttd>&ltUL>
	<% do while not RS.EOF %>
	&ltLI>
	&lta href="<%=RS(2)%>"><%=rs(1)%></a>
	</li>
	<% RS.MoveNext
	loop %>
	</td></tr></table><%
end sub
%>

The first method of incorporating ASP and HTML is to have the programming separate from HTML, using Response.Write to send any HTML scripting to the client. Here is an example.

<% 
	sVar = Response("Count")
	if (sVar = "15Seconds") then
		Response.Write "&ltH1>" & sVar & "</H1>"
	end if
%>

&ltH1><% = sVar %></H1>

A more common example is a looping function that has both ASP code in and out of line with the HTML code. Here is first example again but formatted with the delimiters on the far left margin.

<%
sub X(sQueryText)
	Set RS = oConn.Execute(sQueryText)
%>
	&lttable align="left">&lttr>&lttd>&ltUL>
<% 
	do while not RS.EOF 
%>
		&ltLI>
		&lta href="<% =RS(2) %>"><%=rs(1)%></a>
		</LI>
<% 
		RS.MoveNext
	loop 
%>
	</UL></td></tr></table> 
<%
end sub
%>

Use Include Files

When programming C or Visual Basic, knowing when to use a procedure to encapsulate code that is used again and again is a distinction that separates good from average programmers. In programming Active Server Pages, include files are the equivalent of procedures. For Example, you have 50 Active Server Pages, which include a meta description for search engines like so:

Example.asp

&ltHTML>
&ltHEAD>
	&ltTITLE&gtExample</TITLE>
	&ltMETA Name="description" Content="An Example">
</HEAD>
&ltBODY>
The Example
</BODY>
</HTML>

Example.asp

&ltHTML>
&ltHEAD>
	&ltTITLE&gtExample</TITLE>
	<!--#include virtual="/meta.inc"-->
</HEAD>
&ltBODY>
The Example
</BODY>
</HTML>

meta.inc

&ltMETA Name="description" Content="An Example">

1. Cookie Handling Functions
2. Constent Variable declarations
3. Footers
4. Headers
5. Repeated Text

Know when to use a Sub versus a Function

The Function has the ability of taking and returning parameters as well as a return value. A Sub has the ability to taking and returning parameters but does not have a return value.

A function should always be used if any error can happen inside the function. The first example is a routine that takes as a parameter a string of characters. The code inside the routine should check to see it the string of characters is "" or null before any processing. If the string is null then an error via the return value should be thrown.

If the routine requires absolutely no processing of global or local variables, then use a SUB. An example is an SUB that prints out the current date (using the Date() function) in HTML.

HTML comment beginning for ASP debugging

Begin and end every Function or Sub with HTML debugging statements. This way you don't have to comment out any ASP code when you release and the debug code is always available. Here is how this would look in the INC file:

Admin.inc

<%
Function AdminDisplayDeleteForm(g_iContentID,g_sScriptName,sText,sWhatis)
%>
	<!-- Admin.AdminDisplayDeleteForm B -->
<%
	Response.Write sNewLine
%>
	&ltFORM ACTION="<%=g_sScriptName%>?g_iMode=3&ID=<%=g_iContentID%>" METHOD="POST">
		Do you really want to delete the <%=sWhatis%> with a Description of
		&ltbr>
		&ltb><%=sText%></b>
		&ltbr>
		And an ID of
		&ltbr>
		&ltb><%=g_iContentID%></b>
		&ltBr>
		&ltINPUT TYPE="SUBMIT" NAME="Button" VALUE="Delete">
	</form>
	&ltFORM ACTION="<%=g_sScriptName%>?ID=<%=g_iContentID%>" METHOD="POST">
		&ltINPUT TYPE="SUBMIT" NAME="Button" VALUE="Cancel">		
	</form>

	<!-- Admin.AdminDisplayDeleteForm E -->
<%
	Response.Write sNewLine

	AdminDisplayDeleteForm = 0

end function
%>

Leave plenty of white space and tabs

It's very easy to get into the habit of writing code quickly but not so quickly debugged or maintained. The expense of the project will be in maintenance and debugging. By adding white space and tabs to the code, you are ensuring a degree of logic and readability to your code. Most of the code written in this article uses standard practice white space and tabs and should be easy to read. By interweaving HTML and ASP code, it is twice as important to be able to quickly determine if the cause of your problem is due to HTML or ASP code.

Any HTML tags or attributes should be capitalized

When reading your code, you will need to quickly decipher ASP from HTML. Many editing programs will color-code for you. How many times have you been in someone else's office debugging the code? If the HTML were all capitalized, it would be easy to decipher your HTML versus in-line ASP.

Understand the difference between when to use global variables and when to pass variables

Global variables should be any information that is 'global' to the entire application. You may have a routine that always prints the page title (a global variable) in the &ltH1> tag. As long as that function is used to only print the page title, there is no reason to pass the parameters.

However, assume you have a function that prints out a result set from ADO. This result set can have a different title each time so the title should be passed in as a parameter.